Agent Tools

How Tools Work with Agents

When an agent has tools available:

Tool Discovery: The agent receives descriptions of available tools
Decision Making: Based on the task, the agent decides if and which tools to use
Tool Invocation: The agent calls tools with appropriate parameters
Result Integration: Tool outputs are incorporated into the agent's response

Tool Configuration

Understanding Tool Patterns

Compozy uses three distinct patterns for working with tools:

Tool Definition
Define tools in separate files with resource: tool. This creates reusable tool components.
Tool Reference in Agents
Reference tools in agent configurations using tool-id.
Tool Usage in Tasks
Use tools in task configurations with tool: tool-id.

Basic Tool Assignment

Assign tools to agents in the agent configuration:

agents:
  - id: data-processor
    model:
      provider: openai
      model: gpt-4-turbo-preview
    instructions: |
      You are a data processing assistant.
      Use available tools to fetch, process, and analyze data.
    tools:
      - fetch-data
      - transform-data
      - save-results

Tool References

Tools can be defined in separate files (autoloaded) or inline within the same YAML file. Reference tools by ID in agent configurations; $ref is no longer supported.

# Reference tools defined in the same workflow file
tools:
  - weather_tool
  - calculator

Tool Inheritance

Agents can inherit tools defined at the project and workflow levels so you don't have to repeat shared tool lists everywhere.

1
Precedence
Agent tools > Workflow tools > Project tools. If an agent declares any tools, inheritance is disabled for that agent.
2
Deterministic Ordering
Inherited tools are merged and then sorted alphabetically by ID before being advertised to the LLM.
3
Where to Define
Use tools: in compozy.yaml for shared tools, tools: in workflows for workflow‑specific overrides, and tools: in agents when you need explicit control.

Project-level tools (compozy.yaml)

tools:
  - id: read_file
    description: Read the contents of a file
  - id: write_file
    description: Write content to a file

Workflow overrides (workflow.yaml)

tools:
  - id: write_file
    description: Write with workflow policies

Agent inheritance (agent.yaml)

# No tools declared here → agent inherits project/workflow tools.
agents:
  - id: analyzer
    model:
      provider: openai
      model: gpt-4o

Tool Usage Patterns

Automatic Tool Selection

By default, agents automatically decide when to use tools:

config:
  provider: openai
  model: gpt-4-turbo-preview
  tool_choice: auto  # Default behavior

actions:
  - id: process-request
    prompt: |
      Process the user's request using available tools as needed.
      Request: {{.input.request}}

Forced Tool Usage

Force the agent to use a specific tool:

config:
  tool_choice: "weather_tool"  # Force specific tool

# Or disable tool usage
config:
  tool_choice: none

MCP Tools

Agents can use tools provided by MCP (Model Context Protocol) servers. MCP servers must be configured in the mcps field, separate from standard tools:

MCP servers are configured in the mcps field, not in the tools array. Standard tools and MCP tools are managed separately.

agents:
  - id: system-admin
    instructions: |
      You are a system administrator with access to server tools.
    # Standard tools (defined with resource: tool)
    tools:
      - log-analyzer
    # MCP servers (separate configuration)
    mcps:
      - id: filesystem
        transport: stdio
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/"]

    actions:
      - id: check-logs
        prompt: |
          Use the MCP filesystem tools to:
          1. List files in /var/log
          2. Read the most recent error logs
          3. Summarize any critical issues found

On this page