# Tool YAML Schema
# Defines the expected structure for tool configuration files.
# See docs/specification.md for full details.

type: object
required:
  - name
  - description
  - source
properties:
  name:
    type: string
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: "Namespaced tool name (namespace/short_name)"
  description:
    type: string
    minLength: 1
    description: "Short description of what the tool does"
  source:
    type: string
    enum: [mcp, agent_skill, builtin, custom]
    description: "Source of the tool implementation"
  tool_type:
    type: string
    enum: [tool, validation]
    default: tool
    description: "Discriminator for the tool registry"
  code:
    type: string
    description: "Inline Python code (required when source=custom)"
  mcp_server:
    type: string
    description: "MCP server name (required when source=mcp)"
  mcp_tool_name:
    type: string
    description: "Tool name on MCP server (required when source=mcp)"
  agent_skill_path:
    type: string
    description: "Path to Agent Skills Standard folder (required when source=agent_skill)"
  input_schema:
    type: object
    description: "JSON Schema for tool inputs"
  output_schema:
    type: object
    description: "JSON Schema for tool outputs"
  capability:
    type: object
    properties:
      read_only:
        type: boolean
        default: false
      writes:
        type: boolean
        default: false
      write_scope:
        type: string
      checkpointable:
        type: boolean
        default: false
      checkpoint_scope:
        type: string
        enum: [file, transaction, snapshot, composite]
      side_effects:
        type: array
        items:
          type: string
      idempotent:
        type: boolean
        default: false
      unsafe:
        type: boolean
        default: false
      human_approval_required:
        type: boolean
        default: false
      cost_profile:
        type: string
  resource_slots:
    type: array
    items:
      type: object
      required: [name, resource_type, access]
      properties:
        name:
          type: string
        resource_type:
          type: string
        access:
          type: string
          enum: [read_only, read_write]
        description:
          type: string
        binding:
          type: string
          enum: [contextual, static, parameter]
          default: contextual
        static_resource:
          type: string
        required:
          type: boolean
          default: true
  lifecycle:
    type: object
    properties:
      discover:
        type: string
      activate:
        type: string
      deactivate:
        type: string
  timeout:
    type: integer
    minimum: 1
    default: 300
    description: "Execution timeout in seconds"