Agent with Tools Example

This example demonstrates an agent with tool definitions - a calculator that can perform math operations.

Tool Design

Tools should be atomic, well-documented, and have clear parameter schemas. Mark read-only tools appropriately to enable safer execution.

Document

YAML

calculator.adl.yaml

adl_spec: "0.2.0"
name: Calculator
description: A calculator agent that performs math operations.
version: "0.1.0"

data_classification:
  sensitivity: public

model:
  capabilities:
    - function_calling

tools:
  - name: add
    description: Add two numbers
    parameters:
      type: object
      properties:
        a:
          type: number
        b:
          type: number
      required:
        - a
        - b
    returns:
      type: number
    read_only: true
    idempotent: true

  - name: multiply
    description: Multiply two numbers
    parameters:
      type: object
      properties:
        a:
          type: number
        b:
          type: number
      required:
        - a
        - b
    returns:
      type: number
    read_only: true
    idempotent: true

metadata:
  license: MIT
  tags:
    - calculator
    - math

JSON

calculator.adl.json

{
  "adl_spec": "0.2.0",
  "name": "Calculator",
  "description": "A calculator agent that performs math operations.",
  "version": "0.1.0",
  "data_classification": {
    "sensitivity": "public"
  },
  "model": {
    "capabilities": [
      "function_calling"
    ]
  },
  "tools": [
    {
      "name": "add",
      "description": "Add two numbers",
      "parameters": {
        "type": "object",
        "properties": {
          "a": {
            "type": "number"
          },
          "b": {
            "type": "number"
          }
        },
        "required": [
          "a",
          "b"
        ]
      },
      "returns": {
        "type": "number"
      },
      "read_only": true,
      "idempotent": true
    },
    {
      "name": "multiply",
      "description": "Multiply two numbers",
      "parameters": {
        "type": "object",
        "properties": {
          "a": {
            "type": "number"
          },
          "b": {
            "type": "number"
          }
        },
        "required": [
          "a",
          "b"
        ]
      },
      "returns": {
        "type": "number"
      },
      "read_only": true,
      "idempotent": true
    }
  ],
  "metadata": {
    "license": "MIT",
    "tags": [
      "calculator",
      "math"
    ]
  }
}

Key Features

Model Configuration

YAML

model:
  capabilities:
    - function_calling

JSON

{
  "model": {
    "capabilities": [
      "function_calling"
    ]
  }
}

This declares that the agent requires a model with function calling capability.

Tool Definitions

Each tool includes:

Field	Purpose
name	Unique identifier for the tool (must match ^[a-z][a-z0-9_]*$)
description	Human-readable description of what the tool does
parameters	JSON Schema defining the input parameters
returns	JSON Schema defining the return value
read_only	Indicates the tool doesn't modify state
idempotent	Indicates the tool can be safely retried

Metadata

YAML

metadata:
  license: MIT
  tags:
    - calculator
    - math

JSON

{
  "metadata": {
    "license": "MIT",
    "tags": [
      "calculator",
      "math"
    ]
  }
}

Provides additional context about the agent for discovery and licensing.

Notes

Implementation Guidance

• Tool names must be unique within the document
• The parameters and returns fields use JSON Schema
• read_only tools are generally safer and can be executed without confirmation
• idempotent tools can be safely retried on failure

Next Steps

Ready to build a production-ready agent? See Production Agent for a complete example with identity, permissions, security, and more.