​
Structure

tools:
  - id: string # Unique identifier for the tool
    use: string | object # Tool reference (shorthand or detailed)
    config: object # Tool-specific configuration
    env: object # Tool-specific environment variables
    import: string # Path to external tool definition file

    # Inline tool definition
    execute: string # TypeScript or Python code to run
    schema: object # Schema for the tool's input and output
      config: object # Tool-specific configuration
      input: object # Schema for the tool's input parameters
      output: object # Schema for the tool's output format

​
Basic Usage

Tools can be used in three main ways:

tools:
  - id: crypto_price
    use: compozy/tools:crypto-price@1.0.0

Each tool can be configured using the config property and environment variables:

tools:
  - id: crypto_price
    use: compozy/tools:crypto-price
    config:
      api_key: "{{ env.API_KEY }}"
      currency: "USD"
    env:
      API_KEY: "your-api-key"

​
Inline Definitions

Tools can be defined inline using either TypeScript or Python code directly in your workflow. Each tool must export a run() function that contains the tool’s logic.

tools:
  - id: double
    execute: |
      export function run(input: { value: number }) {
        return {
          result: input.value * 2
        };
      }
    schema:
      input:
        type: object
        properties:
          value:
            type: number
            description: "Value to double"
        required: [value]
      output:
        type: object
        properties:
          result:
            type: number
            description: "The doubled value"
        required: [result]

​
Deno Modules

You can use Deno modules in your tool’s TypeScript code:

import { crypto } from "jsr:@std/crypto";
import lodash from "npm:lodash";

​
Schema Definition

When creating a tool, you define three types of schemas:

1

Configuration Schema

Defines the structure of the config object

2

Input Schema

Defines the structure of runtime parameters (used with with)

3

Output Schema

Defines the structure of the tool’s output

Here’s an example of a tool definition:

tools:
  - id: crypto_price
    execute: |
      type Input = {
        symbol: string
      }

      type Config = {
        api_key: string
        currency?: string
      }

      export function run(input: Input, config: Config) {
        return {
          price: 0,
          currency: config.currency || 'USD'
        };
      }
    schema:
      config:
        type: object
        properties:
          api_key:
            type: string
            description: "API key for the cryptocurrency data provider"
          currency:
            type: string
            description: "Default currency for price conversion"
            default: "USD"
        required: [api_key]

      input:
        type: object
        properties:
          symbol:
            type: string
            description: "Cryptocurrency symbol (e.g., BTC, ETH)"
        required: [symbol]

      output:
        type: object
        properties:
          price:
            type: number
            description: "Current price of the cryptocurrency"
          currency:
            type: string
            description: "Currency of the price"
        required: [price, currency]

This tool can then be used like this:

tools:
  - id: price_checker
    use: ./crypto_price
    config:
      api_key: {{ env.API_KEY }}    # Matches config schema
      currency: "EUR"            # Optional config parameter

tasks:
  - id: check_price
    use: tool(price_checker)
    with:
      symbol: "BTC"             # Matches input schema

​
Key Points

Configuration Schema

The config schema defines persistent configuration options that are set when the tool is initialized.

Input & Output Schema

The input and output schemas define runtime parameters and the tool’s output.

Schema Format

Both configuration and input schemas use JSON Schema for validation and documentation.

Run Function Parameters

The run() function receives both input and config parameters during execution.

Required Fields

Required fields must be specified in the respective required arrays within each schema definition.

​
Best Practices

Tool Organization

  • Use clear, descriptive tool IDs
  • Group related tools together
  • Document tool-specific configuration

Configuration Management

  • Use environment variables for sensitive data
  • Set sensible defaults in tool definitions
  • Override only necessary config at usage points

Error Handling

  • Always check tool error outputs
  • Provide fallback behavior where appropriate
  • Log tool execution metadata for debugging

Security

  • Never expose sensitive credentials in tool code
  • Validate and sanitize all inputs
  • Follow security best practices for external services

​
References