# Tools

Seclai provides built-in tools that AI agents can call during [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) steps. When enabled, tool definitions are injected into the model's prompt as function-calling schemas, allowing the model to call them during generation, inspect the results, and call more tools before producing its final response.

All tools — including web search and web fetch — are **provided by the Seclai platform**, not by the model vendor. This means every model that supports function calling gets access to web search, knowledge base retrieval, content inspection, and memory tools, regardless of whether the vendor offers those capabilities natively.

Tools are enabled per prompt step in the agent editor. Select the tool groups you want available in the **Tools** dropdown when configuring a prompt call step.

## Tools vs. Explicit Steps

Seclai offers two ways to perform the same action — as an explicit agent step in the pipeline, or as a tool the model can call inside a prompt call step. Understanding the tradeoff helps you build agents that are both reliable and flexible.

### Explicit Steps (Deterministic)

Explicit steps run as fixed stages in the agent pipeline. They execute unconditionally (or conditionally via a [Gate](https://seclai.com/docs/agent-steps/control#gate-step)) with parameters you define at design time.

**Example — Summarize a specific webpage every morning:**

1. [Web Fetch](https://seclai.com/docs/agent-steps/integration#web-fetch-step) → fetch `https://example.com/daily-report`
2. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) → "Summarize this report in 3 bullet points"
3. [Send Email](https://seclai.com/docs/agent-steps/delivery#send-email-step) → deliver the summary

Every run fetches the same URL, processes it the same way, and delivers the result. The pipeline is predictable and easy to debug.

**Pros:**

- **Predictable** — Each step runs in a fixed order with known inputs and outputs. Easy to trace and debug.
- **Cheaper** — No extra tokens spent on tool-calling overhead. The model only processes the content it receives.
- **Works with any model** — Doesn't require function-calling support.
- **Easier to test** — You can inspect each step's output individually in the trace.

**Cons:**

- **Rigid** — The pipeline always does the same thing regardless of context. You can't adapt the flow based on what the model finds.
- **Requires upfront knowledge** — You must know the exact URLs, queries, knowledge bases, or memory keys at design time (or derive them from metadata templates).

### Tool-Enabled Prompt Calls (Autonomous)

When you enable tool groups on a prompt call step, the model decides which tools to call, how many times, and in what order. The model can search, read results, refine its approach, and call more tools — all within a single step.

**Example — Research agent that answers arbitrary questions:**

1. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) with `seclai_web_tools` + `seclai_knowledge_base` → "Answer the user's question using web search and our internal knowledge base. Cite your sources."
2. [Display Result](https://seclai.com/docs/agent-steps/delivery#display-result-step) → show the answer

The model autonomously decides whether to search the web, query the knowledge base, or both. It can issue multiple searches, follow up on partial results, and synthesize information from different sources.

**Example — Smart content processor that adapts to document type:**

1. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) with `seclai_content_tools` + `seclai_memory_banks` → "Analyze the incoming document. Check memory for prior context on this topic. Produce a structured analysis and save key findings to memory."

The model inspects the document with content tools, checks memory for related entries, and writes new findings back — all driven by the content rather than a fixed script.

**Pros:**

- **Adaptive** — The model reacts to what it finds. It can search for more detail, try different queries, or skip unnecessary lookups.
- **Handles open-ended tasks** — Research, fact-checking, multi-source aggregation, and exploratory analysis work well because the model drives the process.
- **Fewer steps to maintain** — A single tool-enabled prompt call can replace a chain of explicit steps.

**Cons:**

- **Less predictable** — The model may call tools in unexpected ways or skip calls you expected it to make.
- **Higher token cost** — Each tool call and its results consume tokens. Multiple rounds of tool calls can be expensive.
- **Requires function-calling models** — Only models that support function calling can use tools. See [Models](https://seclai.com/docs/models).
- **Harder to debug** — When the model makes a poor decision about which tools to call, it can be harder to diagnose than a failed explicit step.

### Choosing an Approach

| Scenario                                              | Recommended approach                                                                                                                   |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Fixed URL or query known at design time               | Explicit [Web Fetch](https://seclai.com/docs/agent-steps/integration#web-fetch-step) or [Web Search](https://seclai.com/docs/agent-steps/integration#web-search-step) step |
| Open-ended research across multiple sources           | Prompt call with `seclai_web_tools` and/or `seclai_knowledge_base`                                                                     |
| Always search the same knowledge base                 | Explicit [Search Knowledge Base](https://seclai.com/docs/agent-steps/core#search-knowledge-base-step) step                                               |
| Let the model choose which knowledge base to search   | Prompt call with `seclai_knowledge_base` (model discovers KBs via `list_knowledge_bases`)                                              |
| Process a specific incoming document                  | Explicit [Load Content](https://seclai.com/docs/agent-steps/content) step or [Insight](https://seclai.com/docs/agent-steps/content#insight-step) step                      |
| Explore documents dynamically based on prompt context | Prompt call with `seclai_content_tools`                                                                                                |
| Always write to a specific memory bank and key        | Explicit [Add Memory](https://seclai.com/docs/agent-steps/core#add-memory-step) step                                                                     |
| Let the model decide what to remember                 | Prompt call with `seclai_memory_banks`                                                                                                 |

You can also **combine both approaches** in a single agent. Use explicit steps for the deterministic parts of the pipeline (fetching a known URL, loading a specific document) and tool-enabled prompt calls for the parts that benefit from model autonomy (analysis, synthesis, follow-up research).

---

## Tool Groups

Tools are organized into four groups. Enable one or more groups per prompt call step:

| Group ID                           | Name                  | Tools                                                                                                                                                                     | Purpose                                            |
| ---------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| <code>seclai_web_tools</code>      | Seclai Web Tools      | <code>seclai_web_search</code>, <code>seclai_web_fetch</code>                                                                                                             | Search the web and fetch page content              |
| <code>seclai_knowledge_base</code> | Seclai Knowledge Base | <code>search_knowledge_base</code>, <code>list_knowledge_bases</code>                                                                                                     | Semantic search across your knowledge bases        |
| <code>seclai_content_tools</code>  | Seclai Content Tools  | <code>load_content</code>, <code>peek_content</code>, <code>grep_content</code>, <code>get_content_stats</code>, <code>list_content_sources</code>                        | Inspect and search within indexed source documents |
| <code>seclai_memory_banks</code>   | Seclai Memory Banks   | <code>list_memory_banks</code>, <code>add_chat_turn</code>, <code>add_memory</code>, <code>search_memory</code>, <code>load_chat_history</code>, <code>load_memory</code> | Read and write persistent memory across agent runs |

---

## Web Tools

Web tools let the model search the web and fetch page content during generation. These tools are **provided by the Seclai platform** and available for every model that supports function calling — you don't need a vendor that offers built-in web browsing or internet access. The model decides which URLs to fetch and which queries to run based on the prompt context, making web tools ideal for research tasks where the set of pages isn't known in advance.

**When to use web tools vs. web steps:**

- **Web tools** (`seclai_web_tools` in a prompt call) — The model autonomously decides what to search and fetch. It can issue multiple searches, follow links, and refine queries across tool-call rounds. Best for open-ended research, fact-checking, and multi-source aggregation.
- **[Web Fetch](https://seclai.com/docs/agent-steps/integration#web-fetch-step) / [Web Search](https://seclai.com/docs/agent-steps/integration#web-search-step) steps** — Execute exactly one fetch or search with a fixed (or template-substituted) URL/query. Best for deterministic pipelines where you know the target URL or query ahead of time.

### seclai_web_search

Search the web and return results with titles, descriptions, and content snippets.

| Parameter          | Type    | Required | Description                                           |
| ------------------ | ------- | -------- | ----------------------------------------------------- |
| <code>query</code> | string  | Yes      | The search query                                      |
| <code>limit</code> | integer | No       | Maximum number of results to return (1–20, default 5) |

Each result includes a URL, title, description, and a content snippet from the page.

### seclai_web_fetch

Fetch a web page and return its content in the specified format.

| Parameter           | Type   | Required | Description                                                                                      |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| <code>url</code>    | string | Yes      | The URL of the web page to fetch. Must start with <code>http://</code> or <code>https://</code>. |
| <code>format</code> | string | No       | Output format — <code>markdown</code> (default), <code>rawHtml</code>, or <code>text</code>.     |

Returns the page URL, title, content in the requested format, and content type.

---

## Knowledge Base Tools

Knowledge base tools let the model search your knowledge bases using semantic similarity and discover which knowledge bases are available. How the tools are configured depends on the context:

### Scenarios

**Scenario 1: Knowledge base ID in the prompt**

When the prompt or system prompt explicitly contains a knowledge base ID (e.g. hardcoded or injected via `{{metadata.knowledge_base_id}}`), the model receives `search_knowledge_base` and is expected to call it with the provided ID.

**Scenario 2a: Knowledge base ID in agent run metadata**

When the agent run metadata includes a `knowledge_base_id` field (but the prompt doesn't explicitly mention it), the `search_knowledge_base` tool is included with that ID as the **default** value for the `knowledge_base_id` parameter. The model can call `search_knowledge_base` without specifying the ID — the default is used automatically.

**Scenario 2b: No knowledge base ID available**

When no knowledge base ID is available in metadata or the prompt, both `list_knowledge_bases` and `search_knowledge_base` are included. The model is expected to first call `list_knowledge_bases` to discover available knowledge bases, then call `search_knowledge_base` with a valid ID from the list.

### list_knowledge_bases

List all knowledge bases available in the current account. Returns the ID, name, and description of each knowledge base. The model uses this to discover which knowledge bases it can search.

This tool takes no parameters.

### search_knowledge_base

Search a knowledge base using semantic similarity.

| Parameter                      | Type    | Required            | Description                                                                                                                |
| ------------------------------ | ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| <code>knowledge_base_id</code> | string  | Depends on scenario | The unique identifier of the knowledge base to search. Required in scenarios 1 and 2b. Has a default value in scenario 2a. |
| <code>query</code>             | string  | Yes                 | The search query string                                                                                                    |
| <code>top_n</code>             | integer | No                  | Maximum number of results to return (1–200, default 10)                                                                    |

Each result includes the `source_connection_content_version_id`, source name, content title, matched text, and similarity score — allowing the model to follow up with content tools for deeper inspection.

---

## Content Tools

Content tools let the model inspect source documents connected to your account. Each content tool (except `list_content_sources`) requires a `source_connection_content_version_id` to identify the specific document to operate on.

### Scenarios

**Scenario 1: Content version ID in the prompt**

When the prompt or system prompt explicitly contains a `source_connection_content_version_id` (e.g. hardcoded or injected via `{{metadata.source_connection_content_version_id}}`), the model receives the content tools and is expected to call them with the provided ID. `list_content_sources` is included for discovery of additional content.

**Scenario 2a: Content version ID in agent run metadata**

When the agent run metadata includes a `source_connection_content_version_id` field (e.g. from a _content added_ or _content updated_ trigger), the content tools that require this ID are included with it as the **default** value. The model can call `load_content`, `peek_content`, `grep_content`, or `get_content_stats` without specifying the ID — the default is used automatically. `list_content_sources` is excluded since the target content is already known.

**Scenario 2b: No content version ID available**

When no content version ID is available in metadata or the prompt, all content tools are included along with `list_content_sources`. The model is expected to first call `list_content_sources` to discover available content sources and their content items, then call the other content tools with a valid ID from the results.

### list_content_sources

List the content sources available in the current account. Returns source connections with their recent content items, including the `source_connection_content_version_id` needed to inspect content with other tools.

| Parameter          | Type    | Required | Description                                                      |
| ------------------ | ------- | -------- | ---------------------------------------------------------------- |
| <code>limit</code> | integer | No       | Maximum number of source connections to return (1–20, default 5) |

### load_content

Load the full text content of a specific source document.

| Parameter                                         | Type   | Required | Description                                          |
| ------------------------------------------------- | ------ | -------- | ---------------------------------------------------- |
| <code>source_connection_content_version_id</code> | string | Yes      | The unique identifier of the content version to load |

### peek_content

Read a character range from a source document. Useful for reading specific sections without loading the entire document.

| Parameter                                         | Type    | Required | Description                                  |
| ------------------------------------------------- | ------- | -------- | -------------------------------------------- |
| <code>source_connection_content_version_id</code> | string  | Yes      | The unique identifier of the content version |
| <code>start</code>                                | integer | Yes      | The starting character position (0-based)    |
| <code>stop</code>                                 | integer | Yes      | The ending character position (exclusive)    |

### grep_content

Search within a source document for all occurrences of a text query. Returns matching lines with surrounding context.

| Parameter                                         | Type   | Required | Description                                  |
| ------------------------------------------------- | ------ | -------- | -------------------------------------------- |
| <code>source_connection_content_version_id</code> | string | Yes      | The unique identifier of the content version |
| <code>query</code>                                | string | Yes      | The text to search for (case-insensitive)    |

### get_content_stats

Get statistics about a source document including total length, line count, word count, and content type.

| Parameter                                         | Type   | Required | Description                                  |
| ------------------------------------------------- | ------ | -------- | -------------------------------------------- |
| <code>source_connection_content_version_id</code> | string | Yes      | The unique identifier of the content version |

---

## Memory Bank Tools

Memory bank tools let the model read and write persistent memory that survives across agent runs. This is useful for agents that need to remember user preferences, track conversation history, or accumulate knowledge over time. See [Memory Banks](https://seclai.com/docs/memory-banks) for more on memory bank types.

Memory banks come in two types:

- **Conversation** — Chat-style history partitioned by key and speaker (`user` / `assistant`).
- **General** — Flat factual entries partitioned by key, with no speaker.

### list_memory_banks

List all memory banks available in the current account. Returns the ID, name, description, type, and mode of each memory bank. The model uses this to discover which memory banks it can interact with.

This tool takes no parameters.

### add_chat_turn

Record a turn in a **conversation** memory bank. Use <code>add_memory</code> for general banks.

| Parameter                   | Type   | Required | Description                                               |
| --------------------------- | ------ | -------- | --------------------------------------------------------- |
| <code>memory_bank_id</code> | string | Yes      | The unique identifier of the conversation memory bank     |
| <code>key</code>            | string | Yes      | The partition key (typically the conversation/user ID)    |
| <code>content</code>        | string | Yes      | The turn's text content                                   |
| <code>speaker</code>        | string | Yes      | The speaker — <code>user</code> or <code>assistant</code> |

### add_memory

Write a fact to a **general** memory bank, partitioned by key. Use <code>add_chat_turn</code> for conversation banks.

| Parameter                   | Type   | Required | Description                                       |
| --------------------------- | ------ | -------- | ------------------------------------------------- |
| <code>memory_bank_id</code> | string | Yes      | The unique identifier of the general memory bank  |
| <code>key</code>            | string | Yes      | The partition key (e.g. user ID, topic, category) |
| <code>content</code>        | string | Yes      | The text content to store                         |

### search_memory

Search a memory bank using semantic similarity, scoped to a specific key. Works on both conversation and general banks.

| Parameter                   | Type    | Required | Description                                            |
| --------------------------- | ------- | -------- | ------------------------------------------------------ |
| <code>memory_bank_id</code> | string  | Yes      | The unique identifier of the memory bank               |
| <code>query</code>          | string  | Yes      | The search query                                       |
| <code>key</code>            | string  | Yes      | The partition key to search within                     |
| <code>top_n</code>          | integer | No       | Maximum number of results to return (1–50, default 10) |

### load_chat_history

Load chat turns from a **conversation** memory bank in chronological order. Use <code>load_memory</code> for general banks.

| Parameter                   | Type    | Required | Description                                                                   |
| --------------------------- | ------- | -------- | ----------------------------------------------------------------------------- |
| <code>memory_bank_id</code> | string  | Yes      | The unique identifier of the conversation memory bank                         |
| <code>key</code>            | string  | Yes      | The partition key (typically the conversation/user ID)                        |
| <code>order</code>          | string  | No       | Sort order — <code>newest_first</code> (default) or <code>oldest_first</code> |
| <code>limit</code>          | integer | No       | Maximum number of entries to return (1–200, default 50)                       |

### load_memory

Load entries from a **general** memory bank in chronological order. Use <code>load_chat_history</code> for conversation banks.

| Parameter                   | Type    | Required | Description                                                                   |
| --------------------------- | ------- | -------- | ----------------------------------------------------------------------------- |
| <code>memory_bank_id</code> | string  | Yes      | The unique identifier of the general memory bank                              |
| <code>key</code>            | string  | Yes      | The partition key to load entries for                                         |
| <code>order</code>          | string  | No       | Sort order — <code>newest_first</code> (default) or <code>oldest_first</code> |
| <code>limit</code>          | integer | No       | Maximum number of entries to return (1–200, default 50)                       |

---

## Tools vs. Explicit Steps

Seclai offers two ways to perform the same action — as an explicit agent step in the pipeline, or as a tool the model can call inside a prompt call step. Understanding the tradeoff helps you build agents that are both reliable and flexible.

### Explicit Steps (Deterministic)

Explicit steps run as fixed stages in the agent pipeline. They execute unconditionally (or conditionally via a [Gate](https://seclai.com/docs/agent-steps/control#gate-step)) with parameters you define at design time.

**Example — Summarize a specific webpage every morning:**

1. [Web Fetch](https://seclai.com/docs/agent-steps/integration#web-fetch-step) → fetch `https://example.com/daily-report`
2. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) → "Summarize this report in 3 bullet points"
3. [Send Email](https://seclai.com/docs/agent-steps/delivery#send-email-step) → deliver the summary

Every run fetches the same URL, processes it the same way, and delivers the result. The pipeline is predictable and easy to debug.

**Pros:**

- **Predictable** — Each step runs in a fixed order with known inputs and outputs. Easy to trace and debug.
- **Cheaper** — No extra tokens spent on tool-calling overhead. The model only processes the content it receives.
- **Works with any model** — Doesn't require function-calling support.
- **Easier to test** — You can inspect each step's output individually in the trace.

**Cons:**

- **Rigid** — The pipeline always does the same thing regardless of context. You can't adapt the flow based on what the model finds.
- **Requires upfront knowledge** — You must know the exact URLs, queries, knowledge bases, or memory keys at design time (or derive them from metadata templates).

### Tool-Enabled Prompt Calls (Autonomous)

When you enable tool groups on a prompt call step, the model decides which tools to call, how many times, and in what order. The model can search, read results, refine its approach, and call more tools — all within a single step.

**Example — Research agent that answers arbitrary questions:**

1. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) with `seclai_web_tools` + `seclai_knowledge_base` → "Answer the user's question using web search and our internal knowledge base. Cite your sources."
2. [Display Result](https://seclai.com/docs/agent-steps/delivery#display-result-step) → show the answer

The model autonomously decides whether to search the web, query the knowledge base, or both. It can issue multiple searches, follow up on partial results, and synthesize information from different sources.

**Example — Smart content processor that adapts to document type:**

1. [Prompt Call](https://seclai.com/docs/agent-steps/core#prompt-call-step) with `seclai_content_tools` + `seclai_memory_banks` → "Analyze the incoming document. Check memory for prior context on this topic. Produce a structured analysis and save key findings to memory."

The model inspects the document with content tools, checks memory for related entries, and writes new findings back — all driven by the content rather than a fixed script.

**Pros:**

- **Adaptive** — The model reacts to what it finds. It can search for more detail, try different queries, or skip unnecessary lookups.
- **Handles open-ended tasks** — Research, fact-checking, multi-source aggregation, and exploratory analysis work well because the model drives the process.
- **Fewer steps to maintain** — A single tool-enabled prompt call can replace a chain of explicit steps.

**Cons:**

- **Less predictable** — The model may call tools in unexpected ways or skip calls you expected it to make.
- **Higher token cost** — Each tool call and its results consume tokens. Multiple rounds of tool calls can be expensive.
- **Requires function-calling models** — Only models that support function calling can use tools. See [Models](https://seclai.com/docs/models).
- **Harder to debug** — When the model makes a poor decision about which tools to call, it can be harder to diagnose than a failed explicit step.

### Choosing an Approach

| Scenario                                              | Recommended approach                                                                                                                   |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Fixed URL or query known at design time               | Explicit [Web Fetch](https://seclai.com/docs/agent-steps/integration#web-fetch-step) or [Web Search](https://seclai.com/docs/agent-steps/integration#web-search-step) step |
| Open-ended research across multiple sources           | Prompt call with `seclai_web_tools` and/or `seclai_knowledge_base`                                                                     |
| Always search the same knowledge base                 | Explicit [Search Knowledge Base](https://seclai.com/docs/agent-steps/core#search-knowledge-base-step) step                                               |
| Let the model choose which knowledge base to search   | Prompt call with `seclai_knowledge_base` (model discovers KBs via `list_knowledge_bases`)                                              |
| Process a specific incoming document                  | Explicit [Load Content](https://seclai.com/docs/agent-steps/content) step or [Insight](https://seclai.com/docs/agent-steps/content#insight-step) step                      |
| Explore documents dynamically based on prompt context | Prompt call with `seclai_content_tools`                                                                                                |
| Always write to a specific memory bank and key        | Explicit [Add Memory](https://seclai.com/docs/agent-steps/core#add-memory-step) step                                                                     |
| Let the model decide what to remember                 | Prompt call with `seclai_memory_banks`                                                                                                 |

## Usage Notes

- Tools are available for both **simple format** and **JSON template format** prompt call steps.
- Multiple tool groups can be enabled on a single prompt call step.
- The model decides when and how to call tools based on the prompt and available context.
- Multiple tool-call rounds are supported — the model can call tools, receive results, and call more tools before producing its final response.
- Tool results are included in the conversation context and count toward the model's token usage.
- All tools are platform-provided — web search, knowledge base retrieval, and memory tools work with any function-calling model, regardless of vendor.
- Not all models support function calling. Look for the tool-use badge in the [Models](https://seclai.com/docs/models) catalog to find compatible models.

## Next Steps

- [Prompt Call Step](https://seclai.com/docs/agent-steps/core#prompt-call-step) — Configure prompt call steps with tools
- [Agents](https://seclai.com/docs/agents) — Create and configure agents
- [Knowledge Bases](https://seclai.com/docs/knowledge-bases) — Set up knowledge bases for semantic search
- [Memory Banks](https://seclai.com/docs/memory-banks) — Create persistent memory for agents
- [Content Sources](https://seclai.com/docs/content-sources) — Connect content sources to your account