For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Agent tool documentation

Tools within an AI Agent sub-process require a documentation entry. The AI Agent reads this documentation to decide which tool to call. Without it, the agent falls back to the element's name, which is usually too vague to select the tool reliably. Missing documentation degrades tool selection rather than causing an outright failure, so this rule reports a warning rather than an error. An undocumented tool might work well during development but fail in production because the LLM does not select it.

To fix this problem, select the tool's entry element, open the Documentation section in the properties panel, and describe what the tool does and when the agent should use it.

The rule checks the tool's entry element—the activity with no incoming sequence flow. Activities reached through a sequence flow are part of the tool's internal flow and do not require their own documentation. Event sub-processes are also skipped because they are triggered by events rather than called by the agent:

Two activities in a tool's sub-flow: the first has no incoming sequence flow and is the tool's entry element, while the second is reached by a sequence flow and is not

No documentation​

The tool's entry activity has no documentation text or contains only whitespace. The agent sees only the element name—for example, Fetch URL—and must guess what the tool does, which inputs matter, and when to use it.

Documentation provided​

The tool's entry activity has a documentation entry such as:

Fetches the contents of a web page. Use this when the user provides or asks about a URL. Returns the raw response body.

A good tool description covers three things: what the tool does, when the agent should use it, and what it returns.

Declare a sub-process as agentic​

This rule applies only within an ad-hoc sub-process recognized as a tool container. Camunda's provided AI Agent element templates are compatible with this rule, regardless of the template version. An ad-hoc sub-process is recognized as a tool container in either of the following ways:

  • Its zeebe:modelerTemplate attribute is set to io.camunda.connectors.agenticai.aiagent.jobworker.v1, which identifies the AI Agent job worker template. Any version of this template is supported.
  • It has a zeebe:property named io.camunda.agenticai.toolContainer with the value true, regardless of whether its tools are invoked by an AI Agent task in the same process or in a separate process. Starting with Camunda 8.10.0-alpha4, the out-of-the-box AI Agent element templates add this property automatically. This property is the supported long-term approach.

If you are not using an out-of-the-box template, or if your template version predates this change, add the property manually. Select the ad-hoc sub-process, open the Extension properties section in the properties panel, and add a property named io.camunda.agenticai.toolContainer with the value true. The property appears as a standard extension property rather than as a dedicated control:

Extension properties section showing the toolContainer property on an ad-hoc sub-process with no element template applied

In the XML, the property appears as follows:

<bpmn:adHocSubProcess id="Tools">
  <bpmn:extensionElements>
    <zeebe:properties>
      <zeebe:property name="io.camunda.agenticai.toolContainer" value="true" />
    </zeebe:properties>
  </bpmn:extensionElements>
</bpmn:adHocSubProcess>

References​