list_documents

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=20

Filtering 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"
}

On this page