dev/page MCP tool
list_folders
List every folder, including empty folders, with explicit entry and page counts.
When to use it
Whenever the user asks to see folders or workspace structure, and before deciding where a page belongs or reorganizing the workspace.
Behavior
Returns the complete, unpaginated folder hierarchy and folder guidance for the selected or default workspace. Every folder is included even when empty. Each folder reports immediate and subtree counts; the workspace root is reported separately.
- Required scopes
- pages:read
- Idempotency
- not-applicable
- Side effects
- None.
- Cost
- One bounded workspace folder query.
- Recovery
- Confirm that the workspace connection is still active.
- Stable errors
- workspace_not_found, workspace_access_revoked, rate_limited, service_not_ready
Exact input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"workspace": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"additionalProperties": false
}Exact success schema
Every successful MCP response uses this validated { contractVersion, requestId, data } envelope.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"contractVersion": {
"type": "string",
"const": "9"
},
"data": {
"type": "object",
"properties": {
"folderGuidance": {
"type": "string",
"description": "Workspace-specific instructions for organizing and placing pages."
},
"folderCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total folders returned, including empty folders."
},
"folders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"pageCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "All pages in this folder and its descendant folders."
},
"parentId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"path": {
"type": "array",
"items": {
"type": "string"
}
},
"updatedAt": {
"type": "string"
},
"childFolderCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Immediate child folders."
},
"directPageCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Pages filed directly in this folder."
},
"entryCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Immediate child folders plus directly filed pages."
}
},
"required": [
"createdAt",
"description",
"id",
"name",
"pageCount",
"parentId",
"path",
"updatedAt",
"childFolderCount",
"directPageCount",
"entryCount"
],
"additionalProperties": false
},
"description": "Complete unpaginated folder hierarchy."
},
"root": {
"type": "object",
"properties": {
"childFolderCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Immediate root folders."
},
"directPageCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Pages filed directly at the workspace root."
},
"entryCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Immediate root folders plus root-level pages."
},
"pageCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "All non-deleted pages in the workspace."
},
"path": {
"minItems": 0,
"maxItems": 0,
"type": "array",
"items": {
"type": "string"
},
"description": "Always empty for the workspace root."
}
},
"required": [
"childFolderCount",
"directPageCount",
"entryCount",
"pageCount",
"path"
],
"additionalProperties": false
},
"workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"isDefault": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"editor"
]
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"id",
"isDefault",
"name",
"role",
"slug"
],
"additionalProperties": false
}
},
"required": [
"folderGuidance",
"folderCount",
"folders",
"root",
"workspace"
],
"additionalProperties": false
},
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"contractVersion",
"data",
"requestId"
],
"additionalProperties": false
}