API Reference

JSON Schema

https://compozy.dev/schemas/tools.json

{
  "type": "object",
  "required": ["tools"],
  "properties": {
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "use", "schema"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the tool"
          },
          "use": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "required": ["repo", "package"],
                "properties": {
                  "repo": { "type": "string" },
                  "package": { "type": "string" },
                  "version": { "type": "string" }
                }
              }
            ],
            "description": "Tool implementation reference"
          },
          "import": {
            "type": "string",
            "description": "Path to external tool definition file"
          },
          "config": {
            "type": "object",
            "description": "Tool-specific configuration options"
          },
          "env": {
            "type": "object",
            "description": "Environment variables specific to this tool instance"
          },
          "schema": {
            "type": "object",
            "required": ["input", "output"],
            "properties": {
              "config": {
                "type": "object",
                "description": "Schema for tool-specific configuration options"
              },
              "input": {
                "type": "object",
                "description": "Schema for the tool's input parameters"
              },
              "output": {
                "type": "object",
                "description": "Schema for the tool's output format"
              }
            }
          }
        }
      }
    }
  }
}

Parameters

array

required

List of tools available in the workflow.

string

required

Unique identifier for the tool. Must be unique across all tools in your workflow.

string | object

required

Tool implementation reference. Can be specified in three formats:

"repo/package" (e.g., "compozy/tools:web-search")
"repo:package@version" (e.g., "compozy/tools:web-search@1.0.0")
Object with repo and package fields

tools:
  - id: web_search
    use: compozy/tools:web-search

tools:
  - id: pdf_reader
    use: compozy/tools:pdf-reader@1.0.0

tools:
  - id: data_processor
    use:
      repo: compozy/tools
      package: data-processor
      version: 2.1.0

string

Path to an external YAML file containing the tool definition. When specified, the tool configuration will be loaded from this file instead of being defined inline.

object

Tool-specific configuration options. Structure varies by tool type.

object

Environment variables specific to this tool instance.

Schema Parameters

object

required

JSON Schema definitions for configuration, input, and output validation.

Show Properties

object

Schema for tool-specific configuration options.

object

required

Schema for the tool’s input parameters.

object

required

Schema for the tool’s output format.

Output References

any

Tool’s output data, accessible via {{ tools.tool_id.output }}. Example:

{
  "data": {
    "results": ["result1", "result2"],
    "metadata": {
      "total": 2,
      "timestamp": "2024-03-20T10:30:00Z"
    }
  }
}

object

Error information if tool execution fails. Example:

{
  "code": "EXECUTION_ERROR",
  "message": "Failed to execute tool",
  "details": {
    "type": "validation_error",
    "reason": "Invalid input parameters"
  }
}

Getting Started

Core Concepts

JSON Schema

Parameters

Schema Parameters

Output References

​JSON Schema

​Parameters

​Schema Parameters

​Output References

JSON Schema

Parameters

Schema Parameters

Output References