agent-tool-dev

Agent Tool Development

Architecture

Tools live in agent/tools/ as TypeScript files. Each file exports a factory function that receives dependencies via injection and returns ToolDefinition (or ToolDefinition[] for related groups).

// agent/types.ts
interface ToolDefinition {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
  execute: (args: Record<string, unknown>) => Promise<unknown>;
}

Tools are registered in agent/index.ts → getTools() method of the ClawWallet class.

Conventions

Naming

• File: wallet-<domain>.ts (e.g., wallet-balance.ts)
• Tool name: wallet_<action> with underscores (e.g., wallet_balance, wallet_contacts_add)
• Factory: createWallet<Domain>Tool (single) or createWallet<Domain>Tools (group returning array)

Dependencies — Inject, Don't Import Globally

Tools receive their dependencies as factory arguments. Common dependencies:

Dependency	Type	Purpose
chainAdapter	ChainAdapter	On-chain queries (balance, gas, tx)
getAddress	() => Address | null	Current wallet address (lazy)
defaultChain	SupportedChain	Fallback chain when user omits it
signerClient	SignerClient	IPC to Desktop Wallet for signing/pairing
policy	PolicyEngine	Spending limits and approvals
contacts	ContactsManager	Address book
history	TransactionHistory	Past transactions
getTransferService	() => TransferService | null	Send tokens (lazy, null before pair)

Parameters Schema

Use JSON Schema-style { type, properties, required }. Always include description on each property.

Return Values

• Success: return a data object with a human-friendly message field
• Error: return { error: "descriptive message" } — never throw
• Blocked: return { blocked: true, reason, approvalId } for policy-blocked actions

Guard Checks

• Wallet not configured → { error: "No wallet configured. Use wallet_create or wallet_import first." }
• Relay not connected → { error: "..." }
• Always validate required state before proceeding