◈
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: 3600Usage
# 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 timeBest 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