> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Learn about the parameters and definitions of tools in Compozy.

## JSON Schema

```json https://compozy.dev/schemas/tools.json [expandable] theme={"dark"}
{
  "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

<ParamField path="tools" type="array" required>
  List of tools available in the workflow.
</ParamField>

<ParamField path="tools[].id" type="string" required>
  Unique identifier for the tool. Must be unique across all tools in your
  workflow.
</ParamField>

<ParamField path="tools[].use" type="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

  <CodeGroup>
    ```yaml Shorthand theme={"dark"}
    tools:
      - id: web_search
        use: compozy/tools:web-search
    ```

    ```yaml Version theme={"dark"}
    tools:
      - id: pdf_reader
        use: compozy/tools:pdf-reader@1.0.0
    ```

    ```yaml Detailed theme={"dark"}
    tools:
      - id: data_processor
        use:
          repo: compozy/tools
          package: data-processor
          version: 2.1.0
    ```
  </CodeGroup>
</ParamField>

<ParamField path="tools[].import" type="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.
</ParamField>

<ParamField path="tools[].config" type="object">
  Tool-specific configuration options. Structure varies by tool type.
</ParamField>

<ParamField path="tools[].env" type="object">
  Environment variables specific to this tool instance.
</ParamField>

## Schema Parameters

<ParamField path="tools[].schema" type="object" required>
  JSON Schema definitions for configuration, input, and output validation.

  <Expandable title="Properties">
    <ParamField path="config" type="object">
      Schema for tool-specific configuration options.
    </ParamField>

    <ParamField path="input" type="object" required>
      Schema for the tool's input parameters.
    </ParamField>

    <ParamField path="output" type="object" required>
      Schema for the tool's output format.
    </ParamField>
  </Expandable>
</ParamField>

## Output References

<ResponseField name="tools.tool_id.output" type="any">
  Tool's output data, accessible via `{{ tools.tool_id.output }}`. Example:

  ```json theme={"dark"}
  {
    "data": {
      "results": ["result1", "result2"],
      "metadata": {
        "total": 2,
        "timestamp": "2024-03-20T10:30:00Z"
      }
    }
  }
  ```
</ResponseField>

<ResponseField name="tools.tool_id.error" type="object">
  Error information if tool execution fails. Example:

  ```json theme={"dark"}
  {
    "code": "EXECUTION_ERROR",
    "message": "Failed to execute tool",
    "details": {
      "type": "validation_error",
      "reason": "Invalid input parameters"
    }
  }
  ```
</ResponseField>