ZeroHuman
◈

Tools

tool.yaml

Define typed integration surfaces with schema, auth, permissions, and runtime gating.

Tools are typed integration surfaces (API/CLI/browser/etc.) with JSON Schema interfaces, OAuth auth, network permissions, and approval gates. Agents use tool definitions to understand what actions are available, what parameters they accept, and what outputs to expect. Tools should carry schemas and be gateable at runtime with per-call approvals, network restrictions, and guardrails.

Schema

tool.yamlyaml
# tool.yaml

name: send-email
version: "1.0"
type: http
description: "Send a transactional email via the email service"

endpoint:
  method: POST
  url: "https://api.example.com/v1/email/send"
  headers:
    Content-Type: application/json
    Authorization: "Bearer {{env.EMAIL_API_KEY}}"

parameters:
  - name: to
    type: string
    required: true
    description: "Recipient email address"
  - name: subject
    type: string
    required: true
    description: "Email subject line"
  - name: body
    type: string
    required: true
    description: "Email body content (HTML supported)"
  - name: from
    type: string
    required: false
    default: "[email protected]"

output:
  type: object
  properties:
    messageId: string
    status: string

rate_limit:
  max_calls: 100
  window: 3600

Usage

# Example: Multi-tool capability
tools:
  - send-email
  - create-ticket
  - update-crm

# Tools can be referenced by name in capabilities
# The runtime resolves tool definitions at execution time

Best Practices

  • ✓One tool per file — keep definitions atomic and reusable
  • ✓Always define parameter types and validation constraints
  • ✓Include rate limiting to prevent agent overuse
  • ✓Use environment variable references for secrets, never hardcode
  • ✓Provide clear output schemas so agents know what to expect
  • ✓Version your tools — breaking changes need a version bump

Anti-Patterns

  • ✗Defining multiple unrelated actions in one tool file
  • ✗Hardcoding credentials or API keys in tool definitions
  • ✗Missing parameter validation — agents will send garbage
  • ✗No rate limiting — agents can and will call tools in loops
  • ✗Vague descriptions that leave agents guessing about behavior