> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sidecars.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge

> Search the workspace knowledge base for ranked excerpts, or ask it a question and get a sourced answer. Both need only knowledge:read.

Search the workspace knowledge base or ask it a question. Both tools need only `knowledge:read`, which every connection has from the start.

| Tool                                    | Scope            | Kind      |
| --------------------------------------- | ---------------- | --------- |
| [`search_knowledge`](#search-knowledge) | `knowledge:read` | read-only |
| [`ask_knowledge`](#ask-knowledge)       | `knowledge:read` | read-only |

## search\_knowledge

**Scope:** `knowledge:read` (granted on first connect) · **Kind:** read-only · **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`

> Hybrid (vector + full-text) search over the organization's ingested
> knowledge base. Returns ranked document excerpts with relevance scores. Use
> for finding source material to reason over yourself.

Use this when you want raw passages to reason over. For a direct answer, use
[`ask_knowledge`](/reference/knowledge#ask_knowledge).

### Parameters

<ParamField body="query" type="string" required>
  The search query. Must be a non-empty string.
</ParamField>

<ParamField body="limit" type="number" default="10">
  Maximum results, 1 to 25. Values outside the range are clamped; a
  non-numeric value falls back to the default.
</ParamField>

### Returns

<ResponseField name="results" type="array">
  Ranked hits, best first.

  <Expandable title="result">
    <ResponseField name="source_id" type="string">
      The knowledge base's id for the ingested source (`provider:org:resource:item`).
      **Not** an artifact id: never pass it to the document tools.
    </ResponseField>

    <ResponseField name="document_id" type="string">The same value as `source_id`, kept for callers that already read it. Prefer `source_id`.</ResponseField>

    <ResponseField name="title" type="string" />

    <ResponseField name="score" type="number">The fused ranking score across the retrieval lanes.</ResponseField>
    <ResponseField name="retrievers" type="string[]">Which lanes found the excerpt (for example `["vector", "text"]`).</ResponseField>
    <ResponseField name="content" type="string">The excerpt, up to 2,000 characters, then `[…truncated]`.</ResponseField>
    <ResponseField name="source" type="string">Where the source came from, in the connector's words (for example `notion:Getting Started`). A label, not a URL; absent when the connector recorded none.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="truncated" type="boolean">
  `true` when results were dropped to keep the response under 50,000
  characters.
</ResponseField>

The text block renders each result as:

```text theme={null}
### <title> (score: <0.0000>, via <retrievers>)
document_id: <id>

<excerpt, up to 2,000 characters, then "[…truncated]">
```

When there are no matches the text is `No results found.` and `results` is
empty. When the response would exceed 50,000 characters, the remaining
results are dropped, `truncated` is `true` and a `[…N more results
truncated]` line is appended. See
[Artifact URLs and document IDs](/reference/artifacts) for why a knowledge
id is never a document id.

### Permissions and side effects

* Needs a token for the workspace with `knowledge:read`.
* Searches only the token's workspace.
* Reads nothing else and changes nothing. The call is recorded in the
  workspace's agent activity history.

### Errors

| Text                                                 | Cause                                 |
| ---------------------------------------------------- | ------------------------------------- |
| `Tool failed: \`query\` must be a non-empty string\` | Empty or missing query                |
| `Tool failed: <backend message>`                     | The knowledge backend was unavailable |

### Example

**Request**

```json theme={null}
{
  "name": "search_knowledge",
  "arguments": { "query": "Acme onboarding checklist", "limit": 3 }
}
```

**Response (text)**

```text theme={null}
### Acme onboarding checklist (score: 0.0328, via vector+text)
document_id: kb_7c2f9e_acme-onboarding

1. Kick-off call with the Acme platform team
2. Provision sandbox credentials
3. Confirm SSO domain ...

### Customer onboarding playbook (score: 0.0311, via vector)
document_id: kb_1a0d44_playbook

Every enterprise onboarding follows the same four phases ...
```

## ask\_knowledge

**Scope:** `knowledge:read` (granted on first connect) · **Kind:** read-only · **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`

> Ask a question about the organization's knowledge base and get an
> LLM-synthesized answer with cited sources. Use when you want a direct
> answer rather than raw excerpts.

### Parameters

<ParamField body="query" type="string" required>
  The question to answer. Must be a non-empty string.
</ParamField>

### Returns

<ResponseField name="answer" type="string">The synthesized answer, citing sources as `[n]`.</ResponseField>

<ResponseField name="sources" type="array">
  The sources the answer drew on, in citation order. Empty when the
  knowledge base had nothing relevant.

  <Expandable title="source">
    <ResponseField name="source_id" type="string">The knowledge base's id for the ingested source. **Not** an artifact id.</ResponseField>
    <ResponseField name="document_id" type="string">The same value as `source_id`, kept for compatibility.</ResponseField>

    <ResponseField name="title" type="string" />

    <ResponseField name="score" type="number" />

    <ResponseField name="source" type="string">The connector's label for where it came from; absent when none was recorded.</ResponseField>
  </Expandable>
</ResponseField>

The text block:

```text theme={null}
<answer>

Sources:
[1] <title> (<document_id>, score <0.0000>)
[2] <title> (<document_id>, score <0.0000>)
```

When the answer cites no sources, only the answer text is returned.

### Permissions and side effects

* Needs a token for the workspace with `knowledge:read`.
* Answers only from the token's workspace.
* Changes nothing. The call is recorded in the workspace's agent activity
  history. The answer is generated by a language model, so treat it as a
  synthesis and follow the cited sources for detail.

### Errors

| Text                                                 | Cause                                 |
| ---------------------------------------------------- | ------------------------------------- |
| `Tool failed: \`query\` must be a non-empty string\` | Empty or missing query                |
| `Tool failed: <backend message>`                     | The knowledge backend was unavailable |

### Example

**Request**

```json theme={null}
{
  "name": "ask_knowledge",
  "arguments": { "query": "Who owns the Acme renewal and when is it due?" }
}
```

**Response (text)**

```text theme={null}
The Acme renewal is owned by Priya Raman on the account team and is due on 30 November 2026. The current proposal extends the contract by two years with a 6% uplift.

Sources:
[1] Acme account plan (kb_5e11b2_acme-plan, score 0.0316)
[2] Renewals tracker Q4 (kb_9d02aa_renewals-q4, score 0.0290)
```