clm_list_foldersList visible folders, Everyone/restricted visibility and limited access; omit inaccessible folders, their ancestors and member lists.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Integer 1..100; omit for default | |
| continuation | No | Prior page cursor | |
| parentFolderId | No | Children of parent; omit for visible root |
Changes observed during successful MCP inspections.
Input schema / properties / continuation / descriptionPrevious value: -"Continuation reference from the previous page"New value: +"Prior page cursor"Input schema / properties / limit / descriptionPrevious value: -"Page size (max 100)"New value: +"Integer 1..100; omit for default"Input schema / properties / parentFolderId / anyOfRemoved value: -[
- {
- "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": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / parentFolderId / descriptionPrevious value: -"Only return folders nested under this parent; omit to list the visible root"New value: +"Children of parent; omit for visible root"Input schema / properties / parentFolderId / formatAdded value: +"uuid"Input schema / properties / parentFolderId / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "continuation": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "folders": {
- "description": "Visible folders in the current page",
- "items": {
- "additionalProperties": false,
- "properties": {
- "id": {
- "allOf": [
- {
- "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": "string"
- },
- {
- "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": "string"
- }
- ],
- "description": "Folder UUID",
- "type": "string"
- },
- "name": {
- "description": "Folder name",
- "minLength": 1,
- "type": "string"
- },
- "parentFolderId": {
- "anyOf": [
- {
- "allOf": [
- {
- "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": "string"
- },
- {
- "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": "string"
- }
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "path": {
- "description": "Visible ancestor path, leaf last",
- "items": {
- "additionalProperties": false,
- "properties": {
- "id": {
- "allOf": [
- {
- "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": "string"
- },
- {
- "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": "string"
- }
- ],
- "description": "Folder UUID",
- "type": "string"
- },
- "name": {
- "description": "Folder name",
- "minLength": 1,
- "type": "string"
- },
- "parentFolderId": {
- "anyOf": [
- {
- "allOf": [
- {
- "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": "string"
- },
- {
- "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": "string"
- }
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- }
- },
- "required": [
- "id",
- "name",
- "parentFolderId"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "id",
- "name",
- "parentFolderId",
- "path"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "hasMore": {
- "description": "Whether another page exists",
- "type": "boolean"
- },
- "limit": {
- "description": "Requested page size",
- "maximum": 9007199254740991,
- "minimum": 1,
- "type": "integer"
- },
- "returned": {
- "description": "Number of folders in this page",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
- }
- },
- "required": [
- "folders",
- "limit",
- "returned",
- "hasMore",
- "continuation"
- ],
- "type": "object"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's job is to add filtering semantics — and it does: inaccessible folders, their ancestors, and member lists are omitted from results. That's real context an agent could not derive from the annotations. It stops short of describing ordering or page-cursor behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The middle clause ('Everyone/restricted visibility and limited access') is dense enough to be slightly ambiguous, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full annotation coverage and a fully documented schema, most of what an agent needs is present. Gaps remain around result ordering, how the continuation cursor behaves in practice, and what fields each returned folder carries (no output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, continuation, and parentFolderId are already fully explained in the schema; the description's 'visible root' merely echoes the parentFolderId description. Baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('List visible folders') plus the visibility scope that governs results. It doesn't explicitly contrast with clm_get_folder or clm_create_folder, but list-vs-get is unambiguous from the names, so only the sibling differentiation is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description conveys that this enumerates visible folders and that inaccessible ones are dropped, and the schema's parentFolderId implies root-vs-children browsing. There is no explicit 'use this when...' or named alternative such as clm_get_folder for a single known folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.