Agent Tools

web_search({
  query: "Next.js 14 app router",
  count: 5,
  freshness: "pw"  // past week
})

// Returns:
{
  ok: true,
  result_count: 5,
  results: [
    {
      title: "App Router - Next.js Documentation",
      url: "https://nextjs.org/docs/app",
      description: "The Next.js App Router introduces a new model for building applications...",
      age: "2 weeks ago"
    },
    // ... more results
  ]
}

send_message({
  recipient: "team-chat",  // alias from /link command
  message: "Deployment complete. All systems operational."
})

// Returns:
{
  ok: true,
  recipient: "team-chat",
  message_id: "12345",
  message: "Message sent to 'Team Chat' (telegram:-1001234567890)"
}

list_known_chats()

// Returns:
{
  ok: true,
  chats: [
    {
      alias: "team-chat",
      title: "Engineering Team",
      platform: "telegram",
      chat_id: "-1001234567890",
      type: "supergroup",
      is_main: false,
      is_linked: true
    }
  ]
}

send_image({
  file_path: "workspace/charts/sales-report.png",
  caption: "Q1 Sales Report"
})

send_file({
  file_path: "workspace/exports/data.csv",
  file_type: "document",  // document, audio, video, animation
  caption: "Customer data export"
})

update_working_memory({
  content: `
    Current debugging session:
    - tmux: debug-auth
    - log file: /var/log/auth.log
    - test user: [email protected] (id: 12345)
  `
})

// Returns:
{
  ok: true,
  bytes: 156,
  message: "Working memory updated (156 bytes)"
}

clawhub_install({
  slug: "gcalcli-calendar",
  version: "1.2.0",
  force: false,
  skipSetup: false
})

function createUnifiedTools({
  toolDeps,
  executionContext,
  sourceText,
  createdByUserId,
  getActiveTurnCount,
  chatModel,
  channelSender,
  commandApprovalService,
  sessionKey
}) {
  const tools = {
    // Always available:
    ...createSchedulerTools({ ... }),
    ...createSelfTools({ ... }),
  };
  
  // Only if generic tools enabled:
  if (enableGenericTools) {
    Object.assign(tools, {
      ...createStateTools({ ... }),
      ...createWorkspaceTools({ ... }),
      ...createShellTools({ ... }),
      ...createWebSearchTools({ ... }),
      ...createClawhubTools({ ... })
    });
  }
  
  // Only in main session:
  if (executionContext.isMainSession) {
    Object.assign(tools, {
      ...createMessagingTools({ ... }),
      ...createMediaTools({ ... })
    });
  }
  
  // Only in sessions (not scheduled tasks):
  if (sessionKey) {
    Object.assign(tools, {
      ...createWorkingMemoryTools({ ... })
    });
  }
  
  return tools;
}

type ToolExecutionContext = {
  workspaceRoot: string;
  bundledSkillsDir?: string;
  botTimezone: string;
  platform: string;
  chatId?: string;
  threadId?: string;
  directMessagesTopicId?: string;
  runSource: "user-message" | "scheduled-task" | "heartbeat";
  isMainSession: boolean;
};

class ToolExecutionError extends Error {
  code: string;
  message: string;
  hint?: string;
  retryable?: boolean;
}

// Example:
throw new ToolExecutionError({
  code: "FILE_NOT_FOUND",
  message: "Cannot read missing file: config.json",
  hint: "Create the file first with workspace_write",
  retryable: false
});

await withToolLogging({
  context,
  toolName: "workspace_read",
  defaultCode: "WORKSPACE_READ_FAILED",
  input: { path, format },
  action: async () => {
    // Tool implementation
  }
});

const MAX_TOOL_PAYLOAD_BYTES = 10 * 1024 * 1024;  // 10MB

ensurePayloadWithinLimit({ value: fileContent, maxBytes: MAX_TOOL_PAYLOAD_BYTES });
ensureJsonWithinLimit({ value: parsedJson, maxBytes: MAX_TOOL_PAYLOAD_BYTES });