​
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

​
tools
array
required

List of tools available in the workflow.

​
tools[].id
string
required

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

​
tools[].use
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[].import
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.

​
tools[].config
object

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

​
tools[].env
object

Environment variables specific to this tool instance.

​
Schema Parameters

​
tools[].schema
object
required

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

​
Output References

​
tools.tool_id.output
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"
    }
  }
}
​
tools.tool_id.error
object

Error information if tool execution fails. Example:

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