ACAgentic Craft

Intermediate~28 minHazelJS

Tool Contracts and Side Effects

Design @Tool schemas with side-effect class, timeouts, approval, and idempotency as first-class contract fields.

Authors
editorial-team
Published
Last reviewed
Progress is stored locally in this browser.

Direct answer

A tool is a host-executed contract, not a prompt suggestion. Declare name, JSON-ish parameter schema, side-effect class (read / write / irreversible), requiresApproval when needed, timeouts, and idempotency for writes. AgentRuntime validates args; PolicyEngine may deny or gate.

Docs: Agent package. Pattern: /patterns/tool-using-agent.

Worked example — read vs write

typescript
import { Agent, Tool } from '@hazeljs/agent';

@Agent({
  name: 'support-agent',
  systemPrompt: `Always verify the order exists before processing a refund.`,
  maxSteps: 10,
})
export class SupportAgent {
  @Tool({
    description: 'Look up order information by order ID.',
    parameters: [
      { name: 'orderId', type: 'string', description: 'Order ID', required: true },
    ],
  })
  async lookupOrder(input: { orderId: string }) {
    return orders.get(input.orderId); // read — no approval
  }

  @Tool({
    description: 'Process a refund for an order.',
    requiresApproval: true,
    timeout: 30_000,
    retries: 2,
    parameters: [
      { name: 'orderId', type: 'string', required: true },
      { name: 'amount', type: 'number', required: true },
      { name: 'reason', type: 'string', required: true },
      { name: 'idempotencyKey', type: 'string', required: true },
    ],
  })
  async processRefund(input: {
    orderId: string;
    amount: number;
    reason: string;
    idempotencyKey: string;
  }) {
    const existing = await payments.findByIdempotencyKey(input.idempotencyKey);
    if (existing) return existing;
    return payments.refund(input);
  }
}

Inventory template

ToolSide effectApprovalIdempotency
lookupOrderreadnon/a
processRefundwriteyesexecutionId:refund:orderId

Next

/learn/tools-skills-mcp/skillgate-and-mcp-integration-styles · /patterns/idempotent-tool-execution

Artifact: Tool inventory table: name, side-effect, approval, idempotency key

Sources

Related