Hugging Face

Hugging Face Hub: Find, use and view models, datasets, spaces, buckets, papers, documentation and collections. Get daily papers reports, and browse trending content.

hf_fs

Read-only

When to use: Hugging Face Hub models, datasets, Spaces, collections, papers, daily papers, today's trending models, current paper leaderboard, docs, and repository files.

Examples: {"operations":[{"cmd":"ls","args":["hf://models/trending","--limit","10"]}]} {"operations":[{"cmd":"ls","args":["hf://papers/trending"]}]} {"operations":[{"cmd":"ls","args":["hf://papers/daily/latest"]}]} {"operations":[{"cmd":"cat","args":["hf://papers/2501.00001/paper.md"]}]}

Use hf_fs for Hugging Face Hub filesystem operations. Call it with operations, an array of {cmd, args} items; multiple operations may be submitted together.

Usage: {"operations":[{"cmd":"ls","args":["hf://models/org/repo"]}]}

Grammar; each string below is one args array item: ls URI [--recursive] [--glob GLOB] [--type TYPE] [--sort SORT] [--limit N] cat URI [--offset N] [--max-bytes N] attach URI [--max-bytes N] stat URI find URI [--name GLOB] [--path GLOB] [--type TYPE] [--limit N] search URI [QUERY] [--type TYPE] [--sort SORT] [--tag TAG] [--kind mcp] [--limit N]

Use search for resource discovery, not repository-content search; ls for a known directory, find for recursive file discovery by name/path (not file contents), stat for filesystem metadata or an uncertain target type, cat for text contents, and attach for a complete JPEG, PNG, or WebP image. When the request gives an exact text-file URI, use cat directly; do not add ls or stat first. stat does not read the contents of JSON, Markdown, or other text files.

Search scopes: hf://models[/OWNER], hf://datasets[/OWNER], hf://spaces[/OWNER], hf://collections[/OWNER], hf://papers, and hf://docs[/...]. Repository and repository-file scopes are not supported: search a resource root or owner scope to discover resources; use find for file discovery within a repository or cat for a known text file. Paper and documentation search require QUERY. --tag (repeatable) and --kind are supported only on exactly hf://spaces, not owner scopes or other roots. The only valid --kind value is mcp, which selects MCP Spaces. Use ls hf://models/trending, hf://datasets/trending, hf://spaces/trending, or hf://papers/trending for trending listings. hf://papers/ID is a paper directory, not paper text. Use cat hf://papers/ID/paper.md for paper text and cat hf://papers/ID/metadata.json for metadata. No preliminary listing is needed for these known paths. Use ls hf://papers/ID to discover other resources. Omit --limit, --sort, and --type unless the request requires them. Limits and path-specific behavior are documented at hf://README.md. Issue one hf_fs call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`operations`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	Yes
`truncated`	No
`truncation_reason`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 29, 2026

changedOutput schema / properties / results / items / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "index": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "output_truncated": {
-        "type": "boolean"
-      },
-      "result": {
-        "additionalProperties": false,
-        "allOf": [
-          {
-            "if": {
-              "properties": {
-                "op": {
-                  "const": "attach"
-                }
-              },
-              "required": [
-                "op"
-              ]
-            },
-            "then": {
-              "properties": {
-                "bytes": {
-                  "maximum": 8388608,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "mime_type": {
-                  "enum": [
-                    "image/jpeg",
-                    "image/png",
-                    "image/webp"
-                  ],
-                  "type": "string"
-                },
-                "path": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "path",
-                "mime_type",
-                "bytes"
-              ]
-            }
-          }
-        ],
-        "properties": {
-          "arxiv_url": {
-            "type": "string"
-          },
-          "bytes": {
-            "type": "number"
-          },
-          "content": {
-            "type": "string"
-          },
-          "content_type": {
-            "enum": [
-              "application/json",
-              "text/markdown"
-            ],
-            "type": "string"
-          },
-          "daily_papers_date": {
-            "type": "string"
-          },
-          "daily_papers_uri": {
-            "type": "string"
-          },
-          "entries": {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "anchor": {
-                  "type": "string"
-                },
-                "arxiv_url": {
-                  "type": "string"
-                },
-                "category": {
-                  "type": "string"
-                },
-                "content_type": {
-                  "enum": [
-                    "application/json",
-                    "text/markdown"
-                  ],
-                  "type": "string"
-                },
-                "created_at": {
-                  "type": "string"
-                },
-                "daily_papers_date": {
-                  "type": "string"
-                },
-                "daily_papers_uri": {
-                  "type": "string"
-                },
-                "description": {
-                  "type": "string"
-                },
-                "downloads": {
-                  "type": "number"
-                },
-                "gated": {
-                  "anyOf": [
-                    {
-                      "const": false,
-                      "type": "boolean"
-                    },
-                    {
-                      "enum": [
-                        "auto",
-                        "manual"
-                      ],
-                      "type": "string"
-                    }
-                  ]
-                },
-                "lfs": {
-                  "type": "boolean"
-                },
-                "library": {
-                  "type": "string"
-                },
-                "likes": {
-                  "type": "number"
-                },
-                "name": {
-                  "type": "string"
-                },
-                "observed_at": {
-                  "type": "string"
-                },
-                "path": {
-                  "type": "string"
-                },
-                "private": {
-                  "type": "boolean"
-                },
-                "published_at": {
-                  "type": "string"
-                },
-                "repo_type": {
-                  "enum": [
-                    "model",
-                    "dataset",
-                    "space",
-                    "bucket"
-                  ],
-                  "type": "string"
-                },
-                "sdk": {
-                  "type": "string"
-                },
-                "semantic_relevance": {
-                  "type": "number"
-                },
-                "size": {
-                  "type": "number"
-                },
-                "tags": {
-                  "items": {
-                    "type": "string"
-                  },
-                  "type": "array"
-                },
-                "target_uri": {
-                  "type": "string"
-                },
-                "task": {
-                  "type": "string"
-                },
-                "title": {
-                  "type": "string"
-                },
-                "total_files": {
-                  "type": "number"
-                },
-                "trending_score": {
-                  "type": "number"
-                },
-                "type": {
-                  "enum": [
-                    "file",
-                    "dir",
-                    "repo",
-                    "bucket",
-                    "collection",
-                    "paper",
-                    "link"
-                  ],
-                  "type": "string"
-                },
-                "updated_at": {
-                  "type": "string"
-                },
-                "upvotes": {
-                  "type": "number"
-                },
-                "uri": {
-                  "type": "string"
-                },
-                "url": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "path"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "exists": {
-            "type": "boolean"
-          },
-          "lfs": {
-            "type": "boolean"
-          },
-          "mime_type": {
-            "enum": [
-              "image/jpeg",
-              "image/png",
-              "image/webp"
-            ],
-            "type": "string"
-          },
-          "namespace": {
-            "type": "string"
-          },
-          "next_offset": {
-            "type": "number"
-          },
-          "op": {
-            "enum": [
-              "ls",
-              "cat",
-              "attach",
-              "stat",
-              "find",
-              "search"
-            ],
-            "type": "string"
-          },
-          "path": {
-            "type": "string"
-          },
-          "published_at": {
-            "type": "string"
-          },
-          "section": {
-            "type": "string"
-          },
-          "size": {
-            "type": "number"
-          },
-          "target_uri": {
-            "type": "string"
-          },
-          "truncated": {
-            "type": "boolean"
-          },
-          "truncation_message": {
-            "type": "string"
-          },
-          "truncation_reason": {
-            "enum": [
-              "entry_limit",
-              "max_bytes",
-              "limit",
-              "provider_limit"
-            ],
-            "type": "string"
-          },
-          "type": {
-            "enum": [
-              "namespace",
-              "repo",
-              "dir",
-              "file",
-              "collection",
-              "paper",
-              "link",
-              "missing"
-            ],
-            "type": "string"
-          },
-          "uri": {
-            "type": "string"
-          },
-          "url": {
-            "type": "string"
-          },
-          "warnings": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "required": [
-          "uri",
-          "op"
-        ],
-        "type": "object"
-      },
-      "status": {
-        "const": "success",
-        "type": "string"
-      }
-    },
-    "required": [
-      "index",
-      "status",
-      "result"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "error": {
-        "additionalProperties": false,
-        "properties": {
-          "code": {
-            "enum": [
-              "HF_FS_INVALID_ARGUMENT",
-              "HF_FS_NOT_FOUND",
-              "HF_FS_NOT_A_DIRECTORY",
-              "HF_FS_NOT_A_FILE",
-              "HF_FS_UNSUPPORTED_OPERATION",
-              "HF_FS_ACCESS_DENIED",
-              "HF_FS_TEXT_ONLY",
-              "HF_FS_IMAGE_ONLY",
-              "HF_FS_UNSUPPORTED_MEDIA",
-              "HF_FS_IMAGE_TOO_LARGE",
-              "HF_FS_ATTACHMENT_BUDGET_EXCEEDED",
-              "HF_FS_IMAGE_CONTENT_DISABLED",
-              "HF_FS_ATTACHMENT_INTEGRITY"
-            ],
-            "type": "string"
-          },
-          "message": {
-            "type": "string"
-          },
-          "recovery": {
-            "type": "string"
-          },
-          "retryable": {
-            "const": false,
-            "type": "boolean"
-          },
-          "suggestedOperation": {
-            "enum": [
-              "ls",
-              "cat",
-              "attach",
-              "stat",
-              "search"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "recovery",
-          "retryable"
-        ],
-        "type": "object"
-      },
-      "index": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "status": {
-        "const": "error",
-        "type": "string"
-      }
-    },
-    "required": [
-      "index",
-      "status",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "index": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "output_truncated": {
+        "type": "boolean"
+      },
+      "result": {
+        "additionalProperties": false,
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "op": {
+                  "const": "attach"
+                }
+              },
+              "required": [
+                "op"
+              ]
+            },
+            "then": {
+              "properties": {
+                "bytes": {
+                  "maximum": 8388608,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "mime_type": {
+                  "enum": [
+                    "image/jpeg",
+                    "image/png",
+                    "image/webp"
+                  ],
+                  "type": "string"
+                },
+                "path": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "path",
+                "mime_type",
+                "bytes"
+              ]
+            }
+          }
+        ],
+        "properties": {
+          "arxiv_url": {
+            "type": "string"
+          },
+          "bytes": {
+            "type": "number"
+          },
+          "content": {
+            "type": "string"
+          },
+          "content_type": {
+            "enum": [
+              "application/json",
+              "text/markdown"
+            ],
+            "type": "string"
+          },
+          "daily_papers_date": {
+            "type": "string"
+          },
+          "daily_papers_uri": {
+            "type": "string"
+          },
+          "entries": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "anchor": {
+                  "type": "string"
+                },
+                "arxiv_url": {
+                  "type": "string"
+                },
+                "category": {
+                  "type": "string"
+                },
+                "content_type": {
+                  "enum": [
+                    "application/json",
+                    "text/markdown"
+                  ],
+                  "type": "string"
+                },
+                "created_at": {
+                  "type": "string"
+                },
+                "daily_papers_date": {
+                  "type": "string"
+                },
+                "daily_papers_uri": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "downloads": {
+                  "type": "number"
+                },
+                "gated": {
+                  "anyOf": [
+                    {
+                      "const": false,
+                      "type": "boolean"
+                    },
+                    {
+                      "enum": [
+                        "auto",
+                        "manual"
+                      ],
+                      "type": "string"
+                    }
+                  ]
+                },
+                "lfs": {
+                  "type": "boolean"
+                },
+                "library": {
+                  "type": "string"
+                },
+                "likes": {
+                  "type": "number"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "observed_at": {
+                  "type": "string"
+                },
+                "path": {
+                  "type": "string"
+                },
+                "private": {
+                  "type": "boolean"
+                },
+                "published_at": {
+                  "type": "string"
+                },
+                "repo_type": {
+                  "enum": [
+                    "model",
+                    "dataset",
+                    "space",
+                    "bucket"
+                  ],
+                  "type": "string"
+                },
+                "sdk": {
+                  "type": "string"
+                },
+                "semantic_relevance": {
+                  "type": "number"
+                },
+                "size": {
+                  "type": "number"
+                },
+                "tags": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "target_uri": {
+                  "type": "string"
+                },
+                "task": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "total_files": {
+                  "type": "number"
+                },
+                "trending_score": {
+                  "type": "number"
+                },
+                "type": {
+                  "enum": [
+                    "file",
+                    "dir",
+                    "repo",
+                    "bucket",
+                    "collection",
+                    "paper",
+                    "link"
+                  ],
+                  "type": "string"
+                },
+                "updated_at": {
+                  "type": "string"
+                },
+                "upvotes": {
+                  "type": "number"
+                },
+                "uri": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "path"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "exists": {
+            "type": "boolean"
+          },
+          "lfs": {
+            "type": "boolean"
+          },
+          "mime_type": {
+            "enum": [
+              "image/jpeg",
+              "image/png",
+              "image/webp"
+            ],
+            "type": "string"
+          },
+          "namespace": {
+            "type": "string"
+          },
+          "next_offset": {
+            "type": "number"
+          },
+          "op": {
+            "enum": [
+              "ls",
+              "cat",
+              "attach",
+              "stat",
+              "find",
+              "search"
+            ],
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "published_at": {
+            "type": "string"
+          },
+          "section": {
+            "type": "string"
+          },
+          "size": {
+            "type": "number"
+          },
+          "target_uri": {
+            "type": "string"
+          },
+          "truncated": {
+            "type": "boolean"
+          },
+          "truncation_message": {
+            "type": "string"
+          },
+          "truncation_reason": {
+            "enum": [
+              "entry_limit",
+              "max_bytes",
+              "limit",
+              "provider_limit",
+              "output_budget"
+            ],
+            "type": "string"
+          },
+          "type": {
+            "enum": [
+              "namespace",
+              "repo",
+              "dir",
+              "file",
+              "collection",
+              "paper",
+              "link",
+              "missing"
+            ],
+            "type": "string"
+          },
+          "uri": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "warnings": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "uri",
+          "op"
+        ],
+        "type": "object"
+      },
+      "status": {
+        "const": "success",
+        "type": "string"
+      }
+    },
+    "required": [
+      "index",
+      "status",
+      "result"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "error": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "enum": [
+              "HF_FS_INVALID_ARGUMENT",
+              "HF_FS_NOT_FOUND",
+              "HF_FS_NOT_A_DIRECTORY",
+              "HF_FS_NOT_A_FILE",
+              "HF_FS_UNSUPPORTED_OPERATION",
+              "HF_FS_ACCESS_DENIED",
+              "HF_FS_TEXT_ONLY",
+              "HF_FS_IMAGE_ONLY",
+              "HF_FS_UNSUPPORTED_MEDIA",
+              "HF_FS_IMAGE_TOO_LARGE",
+              "HF_FS_ATTACHMENT_BUDGET_EXCEEDED",
+              "HF_FS_IMAGE_CONTENT_DISABLED",
+              "HF_FS_ATTACHMENT_INTEGRITY"
+            ],
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "recovery": {
+            "type": "string"
+          },
+          "retryable": {
+            "const": false,
+            "type": "boolean"
+          },
+          "suggestedOperation": {
+            "enum": [
+              "ls",
+              "cat",
+              "attach",
+              "stat",
+              "search"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "recovery",
+          "retryable"
+        ],
+        "type": "object"
+      },
+      "index": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "status": {
+        "const": "error",
+        "type": "string"
+      }
+    },
+    "required": [
+      "index",
+      "status",
+      "error"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedSep 9, 2026

changedInput schema / properties / operations / items / properties / args / description

Previous value: -"Command arguments. First item must be an hf:// URI, not a local path or bare filename. One argument per array item."New value: +"Command arguments. First item must be an hf:// URI, not a local path or bare filename. One argument per array item. search discovers resources, not repository contents; use root/owner discovery scopes, find for file discovery, or cat for a known text file. --tag and --kind require exactly hf://spaces; the only valid --kind value is mcp."

Changed1 schema field changedAug 26, 2026

changedInput schema / properties / operations / items / properties / args / description

Previous value: -"Command arguments; each array item is one grammar token."New value: +"Command arguments. First item must be an hf:// URI, not a local path or bare filename. One argument per array item."

Changed33 schema fields changedAug 21, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

removedInput schema / properties / args

Removed value: -{
-  "description": "Command arguments; each array item is one grammar token.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedInput schema / properties / cmd

Removed value: -{
-  "description": "Command to execute.",
-  "enum": [
-    "ls",
-    "cat",
-    "attach",
-    "stat",
-    "find",
-    "search"
-  ],
-  "type": "string"
-}

addedInput schema / properties / operations

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "args": {
+        "description": "Command arguments; each array item is one grammar token.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "cmd": {
+        "description": "Command to execute.",
+        "enum": [
+          "ls",
+          "cat",
+          "attach",
+          "stat",
+          "find",
+          "search"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "cmd",
+      "args"
+    ],
+    "type": "object"
+  },
+  "maxItems": 30,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / required

Previous value: -[
-  "cmd",
-  "args"
-]New value: +[
+  "operations"
+]

removedOutput schema / allOf

Removed value: -[
-  {
-    "if": {
-      "properties": {
-        "op": {
-          "const": "attach"
-        }
-      },
-      "required": [
-        "op"
-      ]
-    },
-    "then": {
-      "properties": {
-        "bytes": {
-          "maximum": 8388608,
-          "minimum": 0,
-          "type": "integer"
-        },
-        "mime_type": {
-          "enum": [
-            "image/jpeg",
-            "image/png",
-            "image/webp"
-          ],
-          "type": "string"
-        },
-        "path": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "path",
-        "mime_type",
-        "bytes"
-      ]
-    }
-  }
-]

removedOutput schema / properties / arxiv_url
```
Removed value: -{
-  "type": "string"
-}
```

removedOutput schema / properties / bytes

Removed value: -{
-  "type": "number"
-}

removedOutput schema / properties / content

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / content_type

Removed value: -{
-  "enum": [
-    "application/json",
-    "text/markdown"
-  ],
-  "type": "string"
-}

removedOutput schema / properties / daily_papers_date
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / daily_papers_uri
```
Removed value: -{
-  "type": "string"
-}
```

removedOutput schema / properties / entries

Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "anchor": {
-        "type": "string"
-      },
-      "arxiv_url": {
-        "type": "string"
-      },
-      "category": {
-        "type": "string"
-      },
-      "content_type": {
-        "enum": [
-          "application/json",
-          "text/markdown"
-        ],
-        "type": "string"
-      },
-      "created_at": {
-        "type": "string"
-      },
-      "daily_papers_date": {
-        "type": "string"
-      },
-      "daily_papers_uri": {
-        "type": "string"
-      },
-      "description": {
-        "type": "string"
-      },
-      "downloads": {
-        "type": "number"
-      },
-      "gated": {
-        "anyOf": [
-          {
-            "const": false,
-            "type": "boolean"
-          },
-          {
-            "enum": [
-              "auto",
-              "manual"
-            ],
-            "type": "string"
-          }
-        ]
-      },
-      "lfs": {
-        "type": "boolean"
-      },
-      "library": {
-        "type": "string"
-      },
-      "likes": {
-        "type": "number"
-      },
-      "name": {
-        "type": "string"
-      },
-      "observed_at": {
-        "type": "string"
-      },
-      "path": {
-        "type": "string"
-      },
-      "private": {
-        "type": "boolean"
-      },
-      "published_at": {
-        "type": "string"
-      },
-      "repo_type": {
-        "enum": [
-          "model",
-          "dataset",
-          "space",
-          "bucket"
-        ],
-        "type": "string"
-      },
-      "sdk": {
-        "type": "string"
-      },
-      "semantic_relevance": {
-        "type": "number"
-      },
-      "size": {
-        "type": "number"
-      },
-      "tags": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "target_uri": {
-        "type": "string"
-      },
-      "task": {
-        "type": "string"
-      },
-      "title": {
-        "type": "string"
-      },
-      "total_files": {
-        "type": "number"
-      },
-      "trending_score": {
-        "type": "number"
-      },
-      "type": {
-        "enum": [
-          "file",
-          "dir",
-          "repo",
-          "bucket",
-          "collection",
-          "paper",
-          "link"
-        ],
-        "type": "string"
-      },
-      "updated_at": {
-        "type": "string"
-      },
-      "upvotes": {
-        "type": "number"
-      },
-      "uri": {
-        "type": "string"
-      },
-      "url": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "path"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

removedOutput schema / properties / exists

Removed value: -{
-  "type": "boolean"
-}

removedOutput schema / properties / lfs

Removed value: -{
-  "type": "boolean"
-}

removedOutput schema / properties / mime_type

Removed value: -{
-  "enum": [
-    "image/jpeg",
-    "image/png",
-    "image/webp"
-  ],
-  "type": "string"
-}

removedOutput schema / properties / namespace
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / next_offset
```
Removed value: -{
-  "type": "number"
-}
```

removedOutput schema / properties / op

Removed value: -{
-  "enum": [
-    "ls",
-    "cat",
-    "attach",
-    "stat",
-    "find",
-    "search"
-  ],
-  "type": "string"
-}

removedOutput schema / properties / path

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / published_at
```
Removed value: -{
-  "type": "string"
-}
```

addedOutput schema / properties / results

Added value: +{
+  "items": {
+    "oneOf": [
+      {
+        "additionalProperties": false,
+        "properties": {
+          "index": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "output_truncated": {
+            "type": "boolean"
+          },
+          "result": {
+            "additionalProperties": false,
+            "allOf": [
+              {
+                "if": {
+                  "properties": {
+                    "op": {
+                      "const": "attach"
+                    }
+                  },
+                  "required": [
+                    "op"
+                  ]
+                },
+                "then": {
+                  "properties": {
+                    "bytes": {
+                      "maximum": 8388608,
+                      "minimum": 0,
+                      "type": "integer"
+                    },
+                    "mime_type": {
+                      "enum": [
+                        "image/jpeg",
+                        "image/png",
+                        "image/webp"
+                      ],
+                      "type": "string"
+                    },
+                    "path": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "path",
+                    "mime_type",
+                    "bytes"
+                  ]
+                }
+              }
+            ],
+            "properties": {
+              "arxiv_url": {
+                "type": "string"
+              },
+              "bytes": {
+                "type": "number"
+              },
+              "content": {
+                "type": "string"
+              },
+              "content_type": {
+                "enum": [
+                  "application/json",
+                  "text/markdown"
+                ],
+                "type": "string"
+              },
+              "daily_papers_date": {
+                "type": "string"
+              },
+              "daily_papers_uri": {
+                "type": "string"
+              },
+              "entries": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "anchor": {
+                      "type": "string"
+                    },
+                    "arxiv_url": {
+                      "type": "string"
+                    },
+                    "category": {
+                      "type": "string"
+                    },
+                    "content_type": {
+                      "enum": [
+                        "application/json",
+                        "text/markdown"
+                      ],
+                      "type": "string"
+                    },
+                    "created_at": {
+                      "type": "string"
+                    },
+                    "daily_papers_date": {
+                      "type": "string"
+                    },
+                    "daily_papers_uri": {
+                      "type": "string"
+                    },
+                    "description": {
+                      "type": "string"
+                    },
+                    "downloads": {
+                      "type": "number"
+                    },
+                    "gated": {
+                      "anyOf": [
+                        {
+                          "const": false,
+                          "type": "boolean"
+                        },
+                        {
+                          "enum": [
+                            "auto",
+                            "manual"
+                          ],
+                          "type": "string"
+                        }
+                      ]
+                    },
+                    "lfs": {
+                      "type": "boolean"
+                    },
+                    "library": {
+                      "type": "string"
+                    },
+                    "likes": {
+                      "type": "number"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "observed_at": {
+                      "type": "string"
+                    },
+                    "path": {
+                      "type": "string"
+                    },
+                    "private": {
+                      "type": "boolean"
+                    },
+                    "published_at": {
+                      "type": "string"
+                    },
+                    "repo_type": {
+                      "enum": [
+                        "model",
+                        "dataset",
+                        "space",
+                        "bucket"
+                      ],
+                      "type": "string"
+                    },
+                    "sdk": {
+                      "type": "string"
+                    },
+                    "semantic_relevance": {
+                      "type": "number"
+                    },
+                    "size": {
+                      "type": "number"
+                    },
+                    "tags": {
+                      "items": {
+                        "type": "string"
+                      },
+                      "type": "array"
+                    },
+                    "target_uri": {
+                      "type": "string"
+                    },
+                    "task": {
+                      "type": "string"
+                    },
+                    "title": {
+                      "type": "string"
+                    },
+                    "total_files": {
+                      "type": "number"
+                    },
+                    "trending_score": {
+                      "type": "number"
+                    },
+                    "type": {
+                      "enum": [
+                        "file",
+                        "dir",
+                        "repo",
+                        "bucket",
+                        "collection",
+                        "paper",
+                        "link"
+                      ],
+                      "type": "string"
+                    },
+                    "updated_at": {
+                      "type": "string"
+                    },
+                    "upvotes": {
+                      "type": "number"
+                    },
+                    "uri": {
+                      "type": "string"
+                    },
+                    "url": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "path"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "exists": {
+                "type": "boolean"
+              },
+              "lfs": {
+                "type": "boolean"
+              },
+              "mime_type": {
+                "enum": [
+                  "image/jpeg",
+                  "image/png",
+                  "image/webp"
+                ],
+                "type": "string"
+              },
+              "namespace": {
+                "type": "string"
+              },
+              "next_offset": {
+                "type": "number"
+              },
+              "op": {
+                "enum": [
+                  "ls",
+                  "cat",
+                  "attach",
+                  "stat",
+                  "find",
+                  "search"
+                ],
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "published_at": {
+                "type": "string"
+              },
+              "section": {
+                "type": "string"
+              },
+              "size": {
+                "type": "number"
+              },
+              "target_uri": {
+                "type": "string"
+              },
+              "truncated": {
+                "type": "boolean"
+              },
+              "truncation_message": {
+                "type": "string"
+              },
+              "truncation_reason": {
+                "enum": [
+                  "entry_limit",
+                  "max_bytes",
+                  "limit",
+                  "provider_limit"
+                ],
+                "type": "string"
+              },
+              "type": {
+                "enum": [
+                  "namespace",
+                  "repo",
+                  "dir",
+                  "file",
+                  "collection",
+                  "paper",
+                  "link",
+                  "missing"
+                ],
+                "type": "string"
+              },
+              "uri": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              },
+              "warnings": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "uri",
+              "op"
+            ],
+            "type": "object"
+          },
+          "status": {
+            "const": "success",
+            "type": "string"
+          }
+        },
+        "required": [
+          "index",
+          "status",
+          "result"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "error": {
+            "additionalProperties": false,
+            "properties": {
+              "code": {
+                "enum": [
+                  "HF_FS_INVALID_ARGUMENT",
+                  "HF_FS_NOT_FOUND",
+                  "HF_FS_NOT_A_DIRECTORY",
+                  "HF_FS_NOT_A_FILE",
+                  "HF_FS_UNSUPPORTED_OPERATION",
+                  "HF_FS_ACCESS_DENIED",
+                  "HF_FS_TEXT_ONLY",
+                  "HF_FS_IMAGE_ONLY",
+                  "HF_FS_UNSUPPORTED_MEDIA",
+                  "HF_FS_IMAGE_TOO_LARGE",
+                  "HF_FS_ATTACHMENT_BUDGET_EXCEEDED",
+                  "HF_FS_IMAGE_CONTENT_DISABLED",
+                  "HF_FS_ATTACHMENT_INTEGRITY"
+                ],
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "recovery": {
+                "type": "string"
+              },
+              "retryable": {
+                "const": false,
+                "type": "boolean"
+              },
+              "suggestedOperation": {
+                "enum": [
+                  "ls",
+                  "cat",
+                  "attach",
+                  "stat",
+                  "search"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "recovery",
+              "retryable"
+            ],
+            "type": "object"
+          },
+          "index": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "status": {
+            "const": "error",
+            "type": "string"
+          }
+        },
+        "required": [
+          "index",
+          "status",
+          "error"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "maxItems": 30,
+  "minItems": 1,
+  "type": "array"
+}

removedOutput schema / properties / section

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / size

Removed value: -{
-  "type": "number"
-}

removedOutput schema / properties / target_uri
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / truncation_message
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / truncation_reason / const
```
Added value: +"output_budget"
```

removedOutput schema / properties / truncation_reason / enum

Removed value: -[
-  "entry_limit",
-  "max_bytes",
-  "limit",
-  "provider_limit"
-]

removedOutput schema / properties / type

Removed value: -{
-  "enum": [
-    "namespace",
-    "repo",
-    "dir",
-    "file",
-    "collection",
-    "paper",
-    "link",
-    "missing"
-  ],
-  "type": "string"
-}

removedOutput schema / properties / uri

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / url

Removed value: -{
-  "type": "string"
-}

removedOutput schema / properties / warnings

Removed value: -{
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

changedOutput schema / required

Previous value: -[
-  "uri",
-  "op"
-]New value: +[
+  "results"
+]

Changed4 schema fields changedAug 14, 2026

changedInput schema / properties / cmd / enum

Previous value: -[
-  "ls",
-  "cat",
-  "stat",
-  "find",
-  "search"
-]New value: +[
+  "ls",
+  "cat",
+  "attach",
+  "stat",
+  "find",
+  "search"
+]

addedOutput schema / allOf

Added value: +[
+  {
+    "if": {
+      "properties": {
+        "op": {
+          "const": "attach"
+        }
+      },
+      "required": [
+        "op"
+      ]
+    },
+    "then": {
+      "properties": {
+        "bytes": {
+          "maximum": 8388608,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "mime_type": {
+          "enum": [
+            "image/jpeg",
+            "image/png",
+            "image/webp"
+          ],
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "path",
+        "mime_type",
+        "bytes"
+      ]
+    }
+  }
+]

addedOutput schema / properties / mime_type

Added value: +{
+  "enum": [
+    "image/jpeg",
+    "image/png",
+    "image/webp"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / op / enum

Previous value: -[
-  "ls",
-  "cat",
-  "stat",
-  "find",
-  "search"
-]New value: +[
+  "ls",
+  "cat",
+  "attach",
+  "stat",
+  "find",
+  "search"
+]

Changed3 schema fields changedJul 27, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed4 schema fields changedJul 15, 2026
- addedOutput schema / properties / entries / items / properties / anchor
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / entries / items / properties / category
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / entries / items / properties / semantic_relevance
```
Added value: +{
+  "type": "number"
+}
```
- addedOutput schema / properties / section
```
Added value: +{
+  "type": "string"
+}
```

Changed16 schema fields changedJul 13, 2026

addedInput schema / properties / args

Added value: +{
+  "description": "Command arguments; each array item is one grammar token.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / cmd

Added value: +{
+  "description": "Command to execute.",
+  "enum": [
+    "ls",
+    "cat",
+    "stat",
+    "find",
+    "search"
+  ],
+  "type": "string"
+}

removedInput schema / properties / entry_type

Removed value: -{
-  "description": "Optional ls/find/search result-type filter; it does not change URI interpretation.",
-  "enum": [
-    "file",
-    "dir",
-    "repo",
-    "bucket",
-    "collection",
-    "paper",
-    "link"
-  ],
-  "type": "string"
-}

removedInput schema / properties / glob

Removed value: -{
-  "description": "ls-only glob matched against entries in the listed directory.",
-  "type": "string"
-}

removedInput schema / properties / limit

Removed value: -{
-  "description": "ls/search maximum results. Default 1000 for ls and 100 for search. Paper listings are capped at 100.",
-  "maximum": 10000,
-  "minimum": 1,
-  "type": "integer"
-}

removedInput schema / properties / max_bytes

Removed value: -{
-  "description": "cat max read length. 0 means the maximum allowed 80000 bytes.",
-  "maximum": 80000,
-  "minimum": 0,
-  "type": "integer"
-}

removedInput schema / properties / name

Removed value: -{
-  "description": "find-only glob matched against entry names/basenames.",
-  "type": "string"
-}

removedInput schema / properties / offset

Removed value: -{
-  "description": "cat read start offset.",
-  "minimum": 0,
-  "type": "integer"
-}

removedInput schema / properties / op

Removed value: -{
-  "description": "Operation: ls lists a directory; cat reads a text-like file; stat checks one URI; find filters entries beneath a known directory; search discovers Hub resources from a supported discovery root.",
-  "enum": [
-    "ls",
-    "cat",
-    "stat",
-    "find",
-    "search"
-  ],
-  "type": "string"
-}

removedInput schema / properties / path

Removed value: -{
-  "description": "find-only glob matched against paths relative to the requested directory URI.",
-  "type": "string"
-}

removedInput schema / properties / query

Removed value: -{
-  "description": "search-only keyword or natural-language query. Use a discovery URI: hf://models, hf://datasets, hf://spaces, hf://collections, hf://collections/OWNER, or hf://papers. Paper search is supported only at exactly hf://papers.",
-  "type": "string"
-}

removedInput schema / properties / recursive

Removed value: -{
-  "default": false,
-  "description": "ls-only recursive traversal; unsupported on unbounded discovery roots such as hf://papers.",
-  "type": "boolean"
-}

removedInput schema / properties / sort

Removed value: -{
-  "description": "Optional sort for supported discovery listings/search only. Do not pass sort to hf://papers or dated Daily Papers listings; use ls hf://papers/trending for trending papers.",
-  "enum": [
-    "createdAt",
-    "downloads",
-    "likes",
-    "lastModified",
-    "likes30d",
-    "trendingScore",
-    "mainSize",
-    "id",
-    "trending",
-    "upvotes"
-  ],
-  "type": "string"
-}

removedInput schema / properties / uri

Removed value: -{
-  "description": "Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]] or hf://collections[/OWNER[/SLUG]] or hf://papers[/ARXIV_ID[/PATH]].",
-  "minLength": 1,
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "op",
-  "uri"
-]New value: +[
+  "cmd",
+  "args"
+]

addedOutput schema / properties / warnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed9 schema fields changedJul 12, 2026

addedInput schema / properties / entry_type / description

Added value: +"Optional ls/find/search result-type filter; it does not change URI interpretation."

addedInput schema / properties / glob / description

Added value: +"ls-only glob matched against entries in the listed directory."

changedInput schema / properties / limit / description

Previous value: -"ls/search max result size. ls default 1000; ls hf://papers uses limit for its recent-paper sample (default 10, capped at 100) in addition to structural entries; paper batch and trending listings default to and are capped at 100; search default 100."New value: +"ls/search maximum results. Default 1000 for ls and 100 for search. Paper listings are capped at 100."

changedInput schema / properties / name / description

Previous value: -"find glob matched against entry name/basename."New value: +"find-only glob matched against entry names/basenames."

addedInput schema / properties / op / description

Added value: +"Operation: ls lists a directory; cat reads a text-like file; stat checks one URI; find filters entries beneath a known directory; search discovers Hub resources from a supported discovery root."

changedInput schema / properties / path / description

Previous value: -"find glob matched against entry path relative to the requested URI."New value: +"find-only glob matched against paths relative to the requested directory URI."

changedInput schema / properties / query / description

Previous value: -"Search query for hf://models, hf://datasets, hf://spaces, hf://collections, or hf://papers."New value: +"search-only keyword or natural-language query. Use a discovery URI: hf://models, hf://datasets, hf://spaces, hf://collections, hf://collections/OWNER, or hf://papers. Paper search is supported only at exactly hf://papers."

addedInput schema / properties / recursive / description

Added value: +"ls-only recursive traversal; unsupported on unbounded discovery roots such as hf://papers."

changedInput schema / properties / sort / description

Previous value: -"Sort for discovery listings/search. Use hf://papers/trending for the paper trending view; other sort values are provider-specific."New value: +"Optional sort for supported discovery listings/search only. Do not pass sort to hf://papers or dated Daily Papers listings; use ls hf://papers/trending for trending papers."

Changed29 schema fields changedJul 10, 2026

changedInput schema / properties / entry_type / enum

Previous value: -[
-  "file",
-  "dir",
-  "repo",
-  "bucket",
-  "collection",
-  "link"
-]New value: +[
+  "file",
+  "dir",
+  "repo",
+  "bucket",
+  "collection",
+  "paper",
+  "link"
+]

changedInput schema / properties / limit / description

Previous value: -"ls/search max result size. ls default 1000; search default 100. 0 means the maximum allowed."New value: +"ls/search max result size. ls default 1000; ls hf://papers uses limit for its recent-paper sample (default 10, capped at 100) in addition to structural entries; paper batch and trending listings default to and are capped at 100; search default 100."

changedInput schema / properties / limit / minimum
```
Previous value: -0New value: +1
```

changedInput schema / properties / query / description

Previous value: -"Search query for hf://models, hf://datasets, hf://spaces, or hf://collections."New value: +"Search query for hf://models, hf://datasets, hf://spaces, hf://collections, or hf://papers."

changedInput schema / properties / sort / description

Previous value: -"Search/list sort field."New value: +"Sort for discovery listings/search. Use hf://papers/trending for the paper trending view; other sort values are provider-specific."

changedInput schema / properties / uri / description

Previous value: -"Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]] or hf://collections[/OWNER[/SLUG]]. "New value: +"Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]] or hf://collections[/OWNER[/SLUG]] or hf://papers[/ARXIV_ID[/PATH]]."

addedOutput schema / properties / arxiv_url
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / content_type / const
```
Removed value: -"application/json"
```

addedOutput schema / properties / content_type / enum

Added value: +[
+  "application/json",
+  "text/markdown"
+]

addedOutput schema / properties / daily_papers_date
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / daily_papers_uri
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / arxiv_url
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / entries / items / properties / content_type / const
```
Removed value: -"application/json"
```
addedOutput schema / properties / entries / items / properties / content_type / enum
```
Added value: +[
+  "application/json",
+  "text/markdown"
+]
```
addedOutput schema / properties / entries / items / properties / daily_papers_date
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / daily_papers_uri
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / library
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / observed_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / published_at
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / entries / items / properties / tags

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedOutput schema / properties / entries / items / properties / target_type

Removed value: -{
-  "enum": [
-    "repo",
-    "collection",
-    "paper",
-    "bucket"
-  ],
-  "type": "string"
-}

addedOutput schema / properties / entries / items / properties / trending_score
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / properties / entries / items / properties / type / enum

Previous value: -[
-  "file",
-  "dir",
-  "repo",
-  "bucket",
-  "collection",
-  "link"
-]New value: +[
+  "file",
+  "dir",
+  "repo",
+  "bucket",
+  "collection",
+  "paper",
+  "link"
+]

addedOutput schema / properties / entries / items / properties / url
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / published_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / target_uri
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / truncation_reason / enum

Previous value: -[
-  "entry_limit",
-  "max_bytes",
-  "limit"
-]New value: +[
+  "entry_limit",
+  "max_bytes",
+  "limit",
+  "provider_limit"
+]

changedOutput schema / properties / type / enum

Previous value: -[
-  "namespace",
-  "repo",
-  "dir",
-  "file",
-  "collection",
-  "link",
-  "missing"
-]New value: +[
+  "namespace",
+  "repo",
+  "dir",
+  "file",
+  "collection",
+  "paper",
+  "link",
+  "missing"
+]

addedOutput schema / properties / url
```
Added value: +{
+  "type": "string"
+}
```

Changed20 schema fields changedJul 7, 2026

changedInput schema / properties / entry_type / enum

Previous value: -[
-  "file",
-  "dir",
-  "repo",
-  "bucket"
-]New value: +[
+  "file",
+  "dir",
+  "repo",
+  "bucket",
+  "collection",
+  "link"
+]

changedInput schema / properties / limit / description

Previous value: -"ls max list size. Default 1000. 0 means the maximum allowed 10000."New value: +"ls/search max result size. ls default 1000; search default 100. 0 means the maximum allowed."

addedInput schema / properties / name

Added value: +{
+  "description": "find glob matched against entry name/basename.",
+  "type": "string"
+}

changedInput schema / properties / op / enum

Previous value: -[
-  "ls",
-  "cat",
-  "stat"
-]New value: +[
+  "ls",
+  "cat",
+  "stat",
+  "find",
+  "search"
+]

addedInput schema / properties / path

Added value: +{
+  "description": "find glob matched against entry path relative to the requested URI.",
+  "type": "string"
+}

addedInput schema / properties / query

Added value: +{
+  "description": "Search query for hf://models, hf://datasets, hf://spaces, or hf://collections.",
+  "type": "string"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "Search/list sort field.",
+  "enum": [
+    "createdAt",
+    "downloads",
+    "likes",
+    "lastModified",
+    "likes30d",
+    "trendingScore",
+    "mainSize",
+    "id",
+    "trending",
+    "upvotes"
+  ],
+  "type": "string"
+}

changedInput schema / properties / uri / description

Previous value: -"Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]]. "New value: +"Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]] or hf://collections[/OWNER[/SLUG]]. "

addedOutput schema / properties / content_type

Added value: +{
+  "const": "application/json",
+  "type": "string"
+}

addedOutput schema / properties / entries / items / properties / content_type
```
Added value: +{
+  "const": "application/json",
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / description
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / name
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / entries / items / properties / target_type

Added value: +{
+  "enum": [
+    "repo",
+    "collection",
+    "paper",
+    "bucket"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / entries / items / properties / target_uri
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / entries / items / properties / title
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / entries / items / properties / type / enum

Previous value: -[
-  "file",
-  "dir",
-  "repo",
-  "bucket"
-]New value: +[
+  "file",
+  "dir",
+  "repo",
+  "bucket",
+  "collection",
+  "link"
+]

addedOutput schema / properties / entries / items / properties / upvotes
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / properties / op / enum

Previous value: -[
-  "ls",
-  "cat",
-  "stat"
-]New value: +[
+  "ls",
+  "cat",
+  "stat",
+  "find",
+  "search"
+]

changedOutput schema / properties / truncation_reason / enum

Previous value: -[
-  "entry_limit",
-  "max_bytes"
-]New value: +[
+  "entry_limit",
+  "max_bytes",
+  "limit"
+]

changedOutput schema / properties / type / enum

Previous value: -[
-  "namespace",
-  "repo",
-  "dir",
-  "file",
-  "missing"
-]New value: +[
+  "namespace",
+  "repo",
+  "dir",
+  "file",
+  "collection",
+  "link",
+  "missing"
+]

Changed1 schema field changedJul 2, 2026

changedInput schema / properties / uri / description

Previous value: -"Hugging Face URI in the form hf://models|datasets|spaces|buckets[/OWNER[/NAME[/PATH]]]. Owner-only ls lists repos or buckets. anonymous requests must include an owner."New value: +"Hugging Face URI in the form hf://models|datasets|spaces|buckets/OWNER[/NAME[/PATH]]. "

AddedJul 2, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds genuine operational context beyond that — that `search` indexes only resource roots/owners and not repository contents, that `--tag`/`--kind` work only on exactly hf://spaces, that hf://papers/ID is a directory rather than text, and that limits and path behavior live at hf://README.md. It does not cover error behavior or response shape (though an output schema exists), so it does not reach 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Given six subcommands, a grammar and a set of scoping rules, the length is largely earned, and the 'When to use' block is correctly front-loaded. There is some redundancy: the 'search is discovery, not content search' rule is restated in three places (prose, search-scopes paragraph, and the schema's args description), and the usage example duplicates the first example's shape.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-command virtual filesystem with an output schema present (so return values need not be described), the definition covers scope, command selection, argument grammar, valid enums, unsupported combinations, and known fast paths. An agent has everything required to select the tool and issue a correct call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is effectively nil for the meaningful semantics (the single `operations` param is an open-ended {cmd, args} mini-language), and the description compensates with a full grammar for all six commands, the TYPE/SORT/CMD vocabularies, the `--kind mcp` constraint, and the requirement that args[0] be a canonical hf:// URI. This is far more than the schema conveys and is exactly what an agent needs to construct valid calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb+resource ('Use hf_fs for Hugging Face Hub filesystem operations') and enumerates the exact domains covered (models, datasets, Spaces, collections, papers, docs, repo files) with worked examples. It is unambiguous about what the tool is. It falls short of a 5 only because it never names or contrasts with the sibling tools (hub_repo_search in particular overlaps conceptually with its `search` command).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use routing is given for every command: 'use search for resource discovery, not repository-content search; ls for a known directory, find for recursive file discovery by name/path... stat for filesystem metadata... cat for text contents, and attach for a complete JPEG, PNG, or WebP image.' It also gives negative guidance ('do not add ls or stat first', 'stat does not read the contents of JSON, Markdown'), valid search scopes with explicit exclusions, and a guidance to omit --limit/--sort/--type unless required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Hugging Face tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?