Tool Schema

Configuration parameters passed to the tool separately from input data. Provides static configuration that tools can use for initialization and behavior control. Unlike input parameters, config is not meant to change between tool invocations.

• Use cases: API base URLs, retry policies, timeout settings, feature flags
• Separation: Keeps configuration separate from runtime input data
• Override: Can be overridden at workflow or agent level
• Example:

  config:
    base_url: "https://api.example.com"
    timeout: 30
    retry_count: 3
    headers:
      User-Agent: "Compozy/1.0"

Human-readable description of the tool's functionality and purpose. This description is used by AI agents to understand when and how to use the tool. Should clearly explain capabilities, limitations, and expected use cases.

• Best practices: Be specific about what the tool does and its constraints
• Example: "Read and parse various file formats including JSON, YAML, and CSV with size limits"

Environment variables available during tool execution. Variables are isolated to the tool's execution context for security. Used for configuration, API keys, and runtime settings.

• Security: Variables are only accessible within the tool's execution
• Template support: Values can use template expressions for dynamic configuration
• Example:

  env:
    API_KEY: "{{ .env.SECRET_API_KEY }}"
    BASE_URL: "https://api.example.com"
    DEBUG: "{{ .project.debug | default(false) }}"

Unique identifier for the tool within the project scope. Used for referencing the tool in agent configurations, workflows, and function calls. Must be unique across all tools in the project.

• Examples: "file-reader", "api-client", "data-processor"
• Naming: Use kebab-case for consistency with other Compozy identifiers

JSON schema defining the expected input parameters for the tool. Used for validation before execution and to generate LLM function call definitions. Must follow JSON Schema Draft 7 specification for compatibility.

• When nil: Tool accepts any input format (no validation performed)
• Use cases: Parameter validation, type safety, auto-generated documentation
• Integration: Automatically converts to LLM function parameters

JSON schema defining the expected output format from the tool. Used for validation after execution and documentation purposes. Must follow JSON Schema Draft 7 specification for compatibility.

• When nil: No output validation is performed
• Use cases: Response validation, type safety, workflow data flow verification
• Best practice: Define output schema for tools used in critical workflows

Resource identifier for the autoloader system (must be "tool"). This field enables automatic discovery and registration of tool configurations.

Maximum execution time for the tool in Go duration format. If not specified, uses the global tool timeout from project configuration. This timeout applies to the entire tool execution lifecycle.

• Examples: "30s", "5m", "1h", "500ms"
• Constraints: Must be positive; zero or negative values cause validation errors
• Default fallback: Uses project-level tool timeout when empty

Default input parameters merged with runtime parameters provided by agents. Provides a way to set tool defaults while allowing runtime customization.

• Merge strategy: Runtime parameters override defaults (shallow merge)
• Use cases: Default API URLs, fallback configurations, preset options
• Security note: Avoid storing secrets here; use environment variables instead