Capabilities

The Capabilities screen is where you build the custom actions your AI agents can perform during a conversation — looking up an order, creating a support ticket, posting a lead to your CRM. Open it from AI Agents > Capabilities in the left menu.

You don't need custom tools for standard capabilities: answering from knowledge sources, collecting conversation results, and human handoff are built into Flametree. Build a tool when an agent must work with your own systems.

Two tool-building screens exist right now

The left menu currently shows both Tools and Capabilities under AI Agents. This page covers Capabilities, where a tool is created from Python code through the portal's own forms. Tools is the earlier screen, where a tool group is one uploaded YAML file plus its Python code — still functional, still linked from the menu, and covered separately under Legacy: tool groups below.

Find your way around

Capabilities has five tabs:

• Tools — your tenant's custom tools, one row per tool.
• Skills — a set of tools plus instructions, made available to an agent as one unit at points you configure, instead of being called individually. See Skills below.
• Built-in — the platform's built-in capabilities (for example, image understanding) and which agents use each one.
• Modules — the Python code a tool is built from: uploaded or pasted files, third-party requirements, and dependencies between modules.
• Logs — a history of tool calls, with filters and per-run detail.

Create a tool

1. On the Tools tab, click Add tool (or, on the Modules tab, Create module). Either opens the same tool builder.

2. Add files or code — choose Upload files (.py and .txt, for example a requirements.txt) or Paste code (enter a File name and paste Python directly). Click Next.

   The parser reads plain functions — no decorator or base class required:

   import os
   import requests
   from typing import Optional
   
   def post_lead_to_crm(client_name: str, client_email: str, offering: Optional[str] = None) -> str:
       """Send a customer's contact details to the corporate CRM.
   
       Args:
           client_name: Full name of the client.
           client_email: Email address of the client.
           offering: The product or service the client is interested in, if known.
       """
       api_key = os.environ["CRM_API_KEY"]
       response = requests.post(
           "https://crm.example.com/api/leads",
           json={"name": client_name, "email": client_email, "offering": offering},
           headers={"Authorization": f"Bearer {api_key}"},
       )
       response.raise_for_status()
       return "Lead created in the CRM."

   • The function's docstring becomes the tool's description; a Google-style Args: section fills in each parameter's description.
   • Type hints set each parameter's type. Use Optional[...] for an optional parameter — the newer str | None syntax isn't recognized.
   • A key read from os.environ (like CRM_API_KEY above) is picked up as an environment variable automatically, and marked Secret by default when its name looks like one (TOKEN, KEY, SECRET, PASSWORD, CREDENTIAL).
   • A function whose name starts with _ is treated as a private helper, not a tool candidate.

   

3. Functions — the code is parsed into a module: a named, reusable package of files that one or more tools are built from.

   • Set the Module name.
   • Every Python function found in the code appears in the Functions list. Click Create tool on a function to configure it (see Configure a tool below) — the function's badge changes from Function to Tool once configured. You don't have to turn every function into a tool.
   • Under Module files, Requirements, and Dependencies, add more files, paste additional requirements, or link other modules in your tenant that this one depends on.
   • An Errors and alerts panel on the right — present from the first step onward — flags problems in the code as you go; for example an import that isn't in your requirements, or an environment variable your code reads but never declares.

4. Review — check the tools you configured (name, function, description, connected agents, connected skills) and the module's files, requirements, and dependencies, then save. Saving creates the module and its tools.

   

5. Connection (optional) — connect the new tools to an agent now, or skip this step and connect them later. See Connect a tool to an agent.

   

Configure a tool

Tool settings opens when you click Create tool (or Settings, once configured) on a function. It shows the read-only Function name and its Source file, then:

Field	Description
Tool name	Defaults to the function name, but can be edited separately — the function itself stays unchanged. Shown to the agent's model as the tool it can call.
Description	What the tool does — the model uses this to decide when to call it. Filled in from the function's docstring.
Tags	Pick existing tags or type a new one to create it.
Parameters	One row per function parameter: Name, Type, and an editable Description the model reads. Parameters the parser can't type are shown as read-only System parameter rows.
Environment variables	Values the tool's code needs at runtime. Add a variable's Name and a Value source: Tool value (enter a Value here, optionally marked Secret) or Required on agent (supplied per agent instead of here).
Additional settings	Repeat limit — how many times the tool may run in a session. Allow duplicate calls — whether the same call (same parameters) can run more than once.

Manage tools

The Tools tab lists every tool in your tenant: name, status, tags, connected agents (up to three names, with a count for more), and a Runs/Errors count for a rolling window (3 days by default). Use the Filters panel to narrow the list by tool name, tags, connected agents, usage count, or creation/edit date.

Click a tool to open its detail page:

• Usage — run counts and median duration for a rolling window (3 days by default), and error count, with a Show logs link into the Logs tab filtered to this tool.
• Connected agents — every agent the tool is connected to, with the connection's trigger, the workflow state it's connected in, how its parameters are set, and recent runs/errors. Add connection opens the same connect flow described in Connect a tool to an agent; each row's menu has Edit and Disconnect.
• The same fields as Configure a tool — General (tool name, function name, description, tags), Parameters, Environment variables, Additional settings — editable after creation.

Connect a tool to an agent

Connecting depends on which editor the agent uses:

• Agents on the new workflow editor — open the agent, go to its Capabilities tab (or a state, transition, or event panel in its workflow), and click Connect. Choose the agent, then the connection's Trigger: In a state (with a When setting, for example During conversation), On transition (runs once when the selected transition happens), or On event (runs automatically when the selected event occurs — session start, a new message from the person, or session end). For an agent whose workflow has only one state, the trigger is placed there automatically.
• Agents still on the classic editor — a tool built in Capabilities can't be connected to these agents. Attach a tool group instead, on the legacy Tools screen — see Legacy: tool groups below.

note

Whichever editor an agent uses is decided by whether its workflow has been migrated to the new model — the agent page shows a banner offering to create a new-version copy when it hasn't. See Workflow tab for the canvas itself — states, transitions, and connecting tools and skills from there.

Skills

A skill bundles one or more tools with its own instructions, so an agent works with them as a unit instead of you exposing each tool on its own. Skills live in Capabilities > Skills, alongside Tools.

Create a skill

1. On the Skills tab, click Add skill. This opens the skill's page — the same page you use to edit it afterward.
2. About — set the Skill name (letters, numbers, and underscores only), a Description (the agent uses this to find the skill when access is set to By name or By search — see Connect a skill to an agent), and Tags.
3. Tools — add the tools this skill uses, from your tenant's tools or the platform's built-in tools. Configure how each one runs (see below).
4. Instructions — write what the skill adds to the agent's prompt while it's active: how to use the skill and its tools.
5. Save. The portal blocks the save with This skill cannot be saved yet if a tool's setup fails validation.

Set how a tool in a skill runs

Each tool inside a skill has its own trigger, independent of the others, and a tool can combine both:

• In a state — During conversation (available any time the skill is active), On event: State entered, or On event: State exited.
• On event — the tool runs automatically when a chosen workflow event happens, regardless of state.

Manage skills

The Skills tab lists every skill in your tenant: name and description, tags, and the agents it's connected to. Click a row to open it.

Opening a skill shows:

• About and Instructions — the same fields as when you created the skill, editable.
• Tools — every tool the skill uses, its trigger, whether its parameters are Set by agent or Set manually, and recent runs and errors.
• Connected agents — every agent the skill is connected to, how it's accessed, and which workflow states it applies to.

Deleting a skill checks its impact first: if it's connected anywhere, the portal offers Delete without restart or Delete and restart agents, and lists the affected agents.

Connect a skill to an agent

Connecting depends on which editor the agent uses, the same as tools:

• Agents on the new workflow editor — open the skill's Connected agents section (or the agent's own Capabilities tab > Skills) and click Connect agent. Choose the agent, then how it can access the skill: Always on (instructions and tools available from the start), By name (the agent sees the skill's name and description and opens it when needed), or By search (hidden until the agent finds it by searching skill descriptions), then the workflow state(s) it applies to.
• Agents still on the classic editor — a skill built in Capabilities can't be connected to these agents. A tool group's YAML definition can describe its own skills instead — see Legacy: tool groups.

Browse the Built-in tab

The Built-in tab lists the platform's built-in capabilities (for example, image understanding) with a description of each and an Enabled for column listing the agents that use it, or Not used if none do yet.

Browse the Modules tab

The Modules tab lists your tenant's modules: name, file count, tool count, and last modified date. Click a module to expand its files — File name, Used by tools (which tools reference it), Type (Code or Data), and creation/edit dates. Open in Module editor reopens the tool builder for that module.

Deleting a module is blocked while its tools are still in use: the Delete module? dialog lists the agents, skills, and workflow actions referencing it and asks you to detach them first, instead of letting the delete go through.

Review tool calls in Logs

The Logs tab lists every tool call in your tenant. Filter by status (All/Success/Error/Cancelled), time period, agent, tool, trigger, connection, or session ID. Each row shows when the call ran, which tool and agent, its trigger, duration, and status.

Click a row to open Run details: a summary (agent, time, tool, session ID, trigger, connection, duration, status), the call's Input, its Output on success or Error with an expandable traceback on failure, and the Run ID. From there, Open session jumps to the session the call happened in and Open tool settings jumps to the tool.

Export CSV downloads the filtered list. Run data is kept for 90 days.

Legacy: tool groups

The earlier Tools screen (AI Agents > Tools) manages tool groups — a tool group is one YAML definition file plus the code files it references, usually Python implementations and, when needed, a requirements.txt. One group can provide several related tools, and the same group can be attached to several agents. A group can also contain skills defined the old way — functions that run automatically at fixed points in a conversation.

note

Writing the YAML definition and the Python implementation is a developer task. The full definition format — parameters, implementation bindings, skill triggers, and the built-in system tools — is in the Tool configuration reference.

Find your way around

The page header shows the Tools title with the number of groups, a search field, and the Add tool group button. The screen has two tabs:

• Tool Groups — the tool groups of your tenant.
• Resources — the shared file storage where dependency files live.

On the Tool Groups tab, switch between Cards view and Table view with the toggle in the corner. Click a card or a table row to open the tool group page.

Tool Groups table columns

Column	Description
Tool group	Group name and description.
Tools	The tools and skills the group provides, taken from the definition file. The first four are listed — click the link below them to expand.
Agents	The agents the group is attached to. Click an agent name to open its page.
Created / Modified	Date and time in your tenant timezone. Sortable.
Status	Processing status of the group — see below.

Columns have filter icons for narrowing the table, and the menu button at the end of each row contains Delete. Deleting a group here removes it from all agents it is linked to — the portal asks for confirmation first.

Tool group statuses

Status	Meaning
Progress	The uploaded definition is being processed.
Done	The group is processed and its tools are ready to use.
Incomplete	A dependency file listed in the definition has not been uploaded yet. Upload the missing files on the tool group page.
Error	Processing failed. Open the group and check the definition file.

Create a tool group

1. In the page header, click Add tool group. The Create Tool Group dialog opens.
2. Under Upload YAML File, click Upload file and choose your definition file (.yaml or .yml). The Name and Description fields fill in from the file's name and description and become locked. Alternatively, skip the upload and enter Name and Description manually.
3. Click Save. The message Tool group created successfully! appears, and the tool group page opens.

The group name must be unique — otherwise the dialog shows This tool group name already exists!. Only the definition file is uploaded here; you add Python and other files on the tool group page afterward.

A minimal definition looks like this:

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

• dependencies lists the files the group needs — the implementation code and, if the code uses third-party packages, a requirements.txt. Listed packages are installed automatically.
• Each entry under tools describes one tool: what it does and which parameters it takes. Skills are described the same way with kind: Skill.

Upload or edit tool files

The tool group page is where you complete and maintain the group's files. It has the Code editor in the center and a collapsible Information panel with the group description and the Files list. The header shows the status indicator, the group name, the Modified and Created dates, and the Save button; the menu next to Save contains Delete tool group.

The Files list contains:

• The definition file, marked Main.
• Every file listed under dependencies in the definition. A dependency that has not been uploaded yet appears in red, and selecting it shows the warning File not found. Please, upload a file for this dependency.

Upload a dependency file

1. In Files, click the menu button on the file row.
2. Click Upload file — or Replace file if the file already exists — and choose the file from disk.
3. Wait for the confirmation message. The file is stored in the shared storage shown on the Resources tab.

Edit a file in the portal

1. In Files, click the file. Its content opens in the Code editor.
2. Make your changes. YAML, Python, Markdown, HTML, JSON, Jinja, CSV, and plain-text files are editable; for other types the editor shows This file type is not supported for editing.
3. Click Save. The confirmation Tool group and edited files updated successfully! appears.

Replace the definition file

1. In Files, click the menu button on the Main file row.
2. Click Replace file and choose the new YAML file. The file must contain name and description — the group name and description update from it.

The replacement is applied immediately — you don't need to click Save.

You can also Download file from any uploaded file's menu, and Remove file (dependencies only, with confirmation).

Browse the Resources tab

The Resources tab shows the tenant-wide file storage as a directory tree. Dependency files of all tool groups live here — a definition's dependencies entries are matched against paths in this storage.

• Select a folder, then use New folder to create a subfolder or New file to upload a file into it.
• Select an item and use Delete to remove it or Download to save a file to disk.
• Use the search field to find a file, and click a file to view its content in the File content panel.

warning

Deleting a file that a tool group depends on makes the file missing in that group — the group's tools can fail until you upload it again.

Attach a tool group to an agent

An agent can call a tool only after the tool's group is attached to it. Attaching happens on the agent page in Advanced mode.

1. Open the agent from AI Agents > Agents and switch on Advanced mode.
2. Scroll to the Tool Groups section.
3. Click Add tool group. A dialog opens with all tool groups of your tenant — search by name, description, or label.
4. Select the check boxes of the groups you want and click Apply.
5. Click Save on the agent page.

The section lists the attached groups with their tools, status, and creation date. To detach a group, open the row menu and click Delete — this removes the group from this agent only, not from the portal.

note

Attaching a group authorizes the agent to use it, but each tool runs only where the agent's workflow allows it: add the tool's name under available_tools in every workflow state where the agent may call it, and explain in the state instructions when to use it. Skills run automatically at the points configured in the group's definition. See Advanced mode.

Test tools in the Playground

Test a tool in a safe chat before customers reach it, whichever screen you built it on.

1. Make sure the agent is saved and running.
2. Open the Playground and select the agent.
3. Send a message the tool should handle — for example, ask about an order if the tool looks up orders — and check the reply for the tool's result.
4. To confirm what happened behind the reply: for a tool built in Capabilities, open the Logs tab and find the call; for a tool group, open the test session in Sessions and click Logs — System Logs record tool and skill calls, and Trace Logs show how the model chose its actions.

Common issues

• The Add tool / Add tool group button is disabled. Your role doesn't include tool permissions — ask your administrator. See Roles and permissions.
• A tool or skill built in Capabilities won't connect to my agent. That agent is still on the classic editor. Either attach a tool group instead (see Legacy: tool groups), or move the agent to the new workflow editor first.
• A skill won't save, with "This skill cannot be saved yet." One of its tools failed validation — open the tool's setup in the skill and fix it.
• The upload is rejected with "Only YAML files can be uploaded!" This is the legacy Tools screen's create dialog and Main file row — they accept only the definition file. Upload Python and other files as dependencies on the tool group page.
• The dialog shows "Uploaded YAML file must have name and description. Please, upload a valid YAML file". Add top-level name and description fields to the definition file and upload it again.
• A file in the legacy Files list is red. The definition lists a dependency that hasn't been uploaded. Open the file's row menu and click Upload file.
• The tool group status is Error. Open the group and check the definition file for mistakes — for example, invalid YAML or wrong field names. Fix the file and save, or replace the Main file with a corrected version.
• The classic agent page has no Tool Groups section. Not every agent type supports tool groups — the section appears for most, but not all, agent types.
• The agent never calls the tool. Check, in order: the tool or group is connected and the agent is saved; for a tool group, the tool's name is listed in available_tools of the workflow state the conversation is in (names are case-sensitive) and the state instructions describe when to use it. If the agent was running while you changed the tool, stop it and start it again. Then check the Logs tab (Capabilities) or the Trace Logs of a test session (tool groups) to see what the model considered.
• The tool is called but fails. Open the failed run in Logs (Capabilities) or the session's System Logs (tool groups) to see the error, then check the Python implementation and confirm that all files and requirements are uploaded.

Related pages

• Configure an Agent — the agent page for the new workflow editor, where tools and skills are connected to states, transitions, and events
• Advanced mode — the classic agent page where tool groups are attached and the workflow is configured
• Agents — create and manage agents
• Playground — test an agent without connecting a channel
• Sessions — read system and trace logs for tool and skill calls
• Knowledge Sources — give agents content to answer from, without tools
• Tool configuration reference — the full YAML definition file format for tool groups
• Roles and permissions — who can create, edit, and attach tools and tool groups