# How to Discover and Run Learned Site Tools and Browser Tools With ego-lite

> Discover and run site and browser tools with ego-lite. Use siteSkills or learnContext to find capabilities, then run tools with runSiteTool or runSiteBrowserTool.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Use `siteSkills()` or `learnContext()` to discover available capabilities, then invoke Node tools with `runSiteTool()` and browser tools with `runSiteBrowserTool()` to execute learned automation scripts.**

ego-lite provides a learning subsystem that allows sites to contribute reusable automation tools—JavaScript modules that run either server-side in Node.js or client-side in the browser context. According to the `citrolabs/ego-lite` source code, these **learned site tools** enable agents to programmatically interact with specific domains using pre-defined, domain-specific logic stored in the `skills/ego-browser/learnings/` directory.

## Understanding Tool Types in ego-lite

ego-lite distinguishes between two execution environments for learned tools:

- **Node (server-side) site tools** – Execute inside the Node.js process hosting the ego-lite helpers. Ideal for file-system operations, API calls, or heavy computation. These run via the `runSiteTool()` helper.
- **Browser (client-side) site tools** – Execute in the context of the current web page using the Chrome DevTools Protocol (CDP). Perfect for DOM manipulation, data extraction, or UI interaction. These run via the `runSiteBrowserTool()` helper.

Both types are defined in per-site [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) files located under `skills/ego-browser/learnings/<siteId>/`.

## Discovering Available Site Tools

Before invoking tools, you must identify what capabilities exist for a given URL. ego-lite provides two discovery helpers in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

### Listing Skills with siteSkills()

The `siteSkills()` function returns a structured list of available tools for a specific URL, defaulting to the current page when called without arguments.

```javascript
const skills = await siteSkills();  // Defaults to current page URL
// Returns: [{ siteId, siteName, tools: [{ toolName, toolType, ... }] }, ...]

```

In [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), `siteSkills()` delegates to `siteSkillsForUrl()` and `siteSkillsForUrlCore()` (lines 64–78), which traverse the `skills/ego-browser/learnings/` directory and parse each site's [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) to match the URL against available site IDs.

### Loading Full Context with learnContext()

For detailed information including tool signatures, descriptions, and example snippets, use `learnContext()`.

```javascript
const ctx = await learnContext();  // Includes knowledge notes and tool definitions
console.log(ctx.tools);

```

Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 13–18), `learnContext()` forwards to `loadLearnedContext()` in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 46–58), which aggregates data from the site's [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) and associated Markdown notes files.

## Running Learned Tools

Once you have identified the `siteId` and `toolName`, execute tools using the appropriate helper based on the tool type.

### Executing Node Site Tools with runSiteTool()

Invoke server-side logic using `runSiteTool()`, which loads and executes the tool module within the Node.js process.

```javascript
// Example: Running a timeline extraction tool for x-com
const result = await runSiteTool('x-com', 'extractTimeline', { page: 1 });
console.log('Node tool result:', result);

```

The implementation in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 87–91) forwards the call to `runNodeSiteTool()` in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) (lines 45–75). This function dynamically requires the tool's JavaScript file, resolves the exported callable, and executes it with the current helper context injected automatically.

### Executing Browser Tools with runSiteBrowserTool()

For DOM-centric operations, use `runSiteBrowserTool()` to execute code in the browser context.

```javascript
// Example: Extracting search results from Google
const html = await runSiteBrowserTool('google', 'extractSearchResults', { query: 'ego-lite' });
console.log('Extracted HTML:', html);

```

As implemented in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 99–105), this helper retrieves the raw source via `loadBrowserToolSource()` and evaluates it using `evaluate(wrapBrowserTool(...))` (lines 78–96 in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)). The wrapper injects the provided `args` object and returns the tool's asynchronous result from the page context.

## Complete Workflow Example

This end-to-end example demonstrates discovering and invoking both tool types:

```javascript
// 1. Discover tools for the current page
const { tools } = await learnContext();
console.log('Available tools:', tools.map(t => t.toolName));

// 2. Execute a Node tool
const nodeTool = tools.find(t => t.toolType === 'node');
if (nodeTool) {
  const output = await runSiteTool(nodeTool.siteId, nodeTool.toolName, { foo: 'bar' });
  console.log('Node output:', output);
}

// 3. Execute a Browser tool
const browserTool = tools.find(t => t.toolType === 'browser');
if (browserTool) {
  const data = await runSiteBrowserTool(browserTool.siteId, browserTool.toolName, { query: 'ego' });
  console.log('Browser output:', data);
}

```

Both `runSiteTool()` and `runSiteBrowserTool()` automatically inject the helper context (`helperContext()`) and agent workspace path, allowing learned tools to call other ego-lite helpers like `click()` or `goto()` without additional configuration.

## Summary

- **Two tool types**: Node tools run server-side via `runSiteTool()`; Browser tools run client-side via `runSiteBrowserTool()`.
- **Discovery methods**: Use `siteSkills()` for quick listings or `learnContext()` for detailed signatures and examples.
- **Storage location**: Tool definitions reside in `skills/ego-browser/learnings/<siteId>/manifest.json` with implementations in the `tools/` subdirectory.
- **Automatic context**: Helpers inject the ego-lite environment automatically, enabling seamless helper composition within learned tools.
- **Source locations**: Core logic lives in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) with implementation details in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts).

## Frequently Asked Questions

### What is the difference between Node and Browser tools in ego-lite?

Node tools execute within the Node.js process hosting the ego-lite runtime, enabling file system access, external API calls, and server-side data processing. Browser tools execute via CDP in the context of the current web page, allowing direct DOM manipulation and client-side data extraction. Choose Node tools for backend processing and Browser tools for interacting with rendered web pages.

### How does ego-lite match URLs to learned site tools?

ego-lite uses `siteSkillsForUrlCore()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 64–78) to traverse the `skills/ego-browser/learnings/` directory, reading each site's [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) to match the provided URL against configured site IDs. The [`check-domain-learning.js`](https://github.com/citrolabs/ego-lite/blob/main/check-domain-learning.js) logic validates domain patterns and returns the appropriate skill set for the matching site.

### Can I pass custom arguments to learned tools?

Yes. Both `runSiteTool(siteId, toolName, args?)` and `runSiteBrowserTool(siteId, toolName, args?)` accept an optional `args` object as the third parameter. For Node tools, these arguments are passed directly to the exported function. For Browser tools, the args are serialized and injected into the page context via the `wrapBrowserTool()` function before execution.

### Where are learned tool definitions stored in ego-lite?

Tool definitions are stored in the `skills/ego-browser/learnings/<siteId>/` directory structure. Each site contains a [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) file listing available `nodeTools` and `browserTools`, along with their file paths and callable signatures. The actual JavaScript implementations reside in `tools/*.js` files, while human-readable documentation lives in `notes/*.md` files within the same directory.