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; list and read repository files, model and dataset cards (README, license).

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"]}]} {"operations":[{"cmd":"search","args":["hf://models","--tag","base_model:finetune:org/repo"]}]}

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 filters models, datasets, and Spaces by Hub tag (repeatable; all must match) and applies only to hf://models|datasets|spaces[/OWNER]; omit QUERY when the tag already identifies the target, because QUERY also filters repository names. Derived models carry base_model:ID and base_model:RELATION:ID tags, where RELATION is finetune, adapter, merge, or quantized. --kind applies only to hf://spaces[/OWNER]; the only valid --kind value is mcp, which selects MCP Spaces. Tag families are documented at hf://README.md. 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.

Links: hf://models|datasets|spaces/OWNER/NAME/PATH maps to https://huggingface.co[/datasets|/spaces]/OWNER/NAME/resolve/main/PATH (buckets: https://huggingface.co/buckets/OWNER/NAME/resolve/PATH); URL-encode each path segment. arXiv ids (for example 2502.16161) link papers, models and datasets.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "operations": "<operations>"
    },
    "name": "hf_fs"
  }
}

Input Schema

Name	Required	Description	Default
`operations`	Yes

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 13, 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. 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."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 requires hf://models|datasets|spaces[/OWNER]; --kind requires hf://spaces[/OWNER] and its only valid value is mcp."

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

A3.9/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds real behavioral detail beyond that: which paths are known without a preliminary listing (hf://papers/ID/paper.md, metadata.json), that stat does not read text contents, that --tag is repeatable and all must match, and that --kind only accepts mcp. It stops short of error/partial-failure behavior for multi-operation batches, which matters since up to 30 operations can be submitted in one call.

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

Conciseness5/5

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

Front-loaded with "When to use" and five worked JSON examples before the grammar, then grouped into clearly labeled blocks (Grammar, TYPE, SORT, scopes, trending, links). It is long but every block is task-relevant for a six-command tool; nothing is padding.

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

Completeness2/5

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

Given a single opaque `operations` array whose meaning lives entirely in a free-text grammar, the description is highly complete: command grammar, URI scheme, scope restrictions, tag/kind applicability, trending shortcuts, and link resolution are all specified, and an output schema exists so return values need not be described. Gaps are narrow (batch failure semantics, the 30-item cap, defaults for omitted flags beyond "omit unless required").

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

Parameters4/5

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

Schema coverage is effectively 0% for the single `operations` parameter, yet the description supplies the entire mini-grammar: per-command flags (--recursive, --glob, --type, --sort, --limit, --offset, --max-bytes, --name, --path, --tag, --kind), the TYPE and SORT vocabularies absent from the schema, and the rule that the first arg must be a canonical hf:// URI. Minor unused schema facts remain unexplained (maxItems 30), but the semantics gap is otherwise closed.

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 opens with a concrete scope statement ("Hugging Face Hub models, datasets, Spaces, collections, papers, daily papers, today's trending models, current paper leaderboard, docs") and a verb set (ls/cat/find/search/stat/attach), so an agent knows exactly what resource class it touches. It does not name or contrast the siblings (hub_repo_search, hub_repo_details, hf_whoami), leaving overlap between this tool's `search` and hub_repo_search to be inferred.

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 per situation: "Use search for resource discovery, not repository-content search; ls for a known directory, find for recursive file discovery... cat for text contents, and attach for a complete JPEG, PNG, or WebP image." It also gives negative guidance ("Repository and repository-file scopes are not supported") and an efficiency rule ("When the request gives an exact text-file URI, use cat directly; do not add ls or stat first"), which is unusually actionable.

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

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?