MCP Tools
list_documents
Browse documents with pagination and filtering
Browse all documents in your knowledge base with pagination and filtering options.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | number | OPTIONAL | 20 | Results per page (1-100) |
offset | number | OPTIONAL | 0 | Skip this many results |
sourceType | enum | OPTIONAL | - | Filter by: note, file, url |
tags | string[] | OPTIONAL | - | Filter by tags (AND logic) |
sortBy | enum | OPTIONAL | created_at | Sort by: created_at, updated_at, title |
sortOrder | enum | OPTIONAL | desc | Sort order: asc, desc |
Example Request
{
"limit": 10,
"offset": 0,
"sourceType": "note",
"tags": ["work"],
"sortBy": "created_at",
"sortOrder": "desc"
}Response
{
"documents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Q4 Planning Notes",
"sourceType": "note",
"tags": ["work", "planning"],
"createdAt": "2024-10-15T14:30:00Z",
"updatedAt": "2024-10-15T14:30:00Z"
}
],
"total": 42,
"limit": 10,
"offset": 0,
"hasMore": true
}Output Schema
This tool MUST return structuredContent alongside the text response. The structuredContent object MUST use canonical verbose keys regardless of the COMPACT_RESPONSES setting.
| Field | Type | Description |
|---|---|---|
documents | array | Array of document objects |
documents[].id | string | Document UUID |
documents[].title | string | Document title |
documents[].sourceType | string | Source type (note, file, url) |
documents[].tags | string[] | Document tags |
documents[].createdAt | string | ISO creation timestamp |
documents[].updatedAt | string | ISO update timestamp |
pagination | object | Pagination metadata |
pagination.limit | integer | Page size |
pagination.offset | integer | Current offset |
pagination.total | integer | Total document count |
pagination.hasMore | boolean | Whether more pages exist |
Pagination
Use limit and offset for pagination:
Page 1: limit=10, offset=0
Page 2: limit=10, offset=10
Page 3: limit=10, offset=20Filtering Examples
By Source Type
{ "sourceType": "file" }Returns only uploaded files.
By Multiple Tags
{ "tags": ["work", "q4"] }Returns documents with BOTH tags.
Combined Filters
{
"sourceType": "note",
"tags": ["important"],
"sortBy": "created_at",
"sortOrder": "asc"
}