Knowledge

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`	`knowledge:read`	read-only
`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.

Parameters

string

required

The search query. Must be a non-empty string.

number

default:"10"

Maximum results, 1 to 25. Values outside the range are clamped; a non-numeric value falls back to the default.

Returns

array

Ranked hits, best first.

Show result

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.

string

The same value as source_id, kept for callers that already read it. Prefer source_id.

string

number

The fused ranking score across the retrieval lanes.

string[]

Which lanes found the excerpt (for example ["vector", "text"]).

string

The excerpt, up to 2,000 characters, then […truncated].

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.

boolean

true when results were dropped to keep the response under 50,000 characters.

The text block renders each result as:

### <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 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

{
  "name": "search_knowledge",
  "arguments": { "query": "Acme onboarding checklist", "limit": 3 }
}

Response (text)

### 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

string

required

The question to answer. Must be a non-empty string.

Returns

string

The synthesized answer, citing sources as [n].

array

The sources the answer drew on, in citation order. Empty when the knowledge base had nothing relevant.

Show source

string

The knowledge base’s id for the ingested source. Not an artifact id.

string

The same value as source_id, kept for compatibility.

string

number

string

The connector’s label for where it came from; absent when none was recorded.

The text block:

<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

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

Response (text)

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)

Get started

Use it

Reference

search_knowledge

Parameters

Returns

Permissions and side effects

Errors

Example

ask_knowledge

Parameters

Returns

Permissions and side effects

Errors

Example

​search_knowledge

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

​ask_knowledge

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

search_knowledge

Parameters

Returns

Permissions and side effects

Errors

Example

ask_knowledge

Parameters

Returns

Permissions and side effects

Errors

Example