diff --git a/icechunk-python/python/icechunk/_icechunk_python.pyi b/icechunk-python/python/icechunk/_icechunk_python.pyi
index a92d75b4..b2564187 100644
--- a/icechunk-python/python/icechunk/_icechunk_python.pyi
+++ b/icechunk-python/python/icechunk/_icechunk_python.pyi
@@ -92,12 +92,37 @@ class VirtualChunkContainer:
         """
 
 class VirtualChunkSpec:
-    index: list[int]
-    location: str
-    offset: int
-    length: int
-    etag_checksum: str | None
-    last_updated_at_checksum: datetime.datetime | None
+    """The specification for a virtual chunk reference."""
+    @property
+    def index(self) -> list[int]:
+        """The chunk index, in chunk coordinates space"""
+        ...
+    @property
+    def location(self) -> str:
+        """The URL to the virtual chunk data, something like 's3://bucket/foo.nc'"""
+        ...
+    @property
+    def offset(self) -> int:
+        """The chunk offset within the pointed object, in bytes"""
+        ...
+    @property
+    def length(self) -> int:
+        """The length of the chunk in bytes"""
+        ...
+    @property
+    def etag_checksum(self) -> str | None:
+        """Optional object store e-tag for the containing object.
+
+        Icechunk will refuse to serve data from this chunk if the etag has changed.
+        """
+        ...
+    @property
+    def last_updated_at_checksum(self) -> datetime.datetime | None:
+        """Optional timestamp for the containing object.
+
+        Icechunk will refuse to serve data from this chunk if it has been modified in object store after this time.
+        """
+        ...
 
     def __init__(
         self,
diff --git a/icechunk-python/python/icechunk/store.py b/icechunk-python/python/icechunk/store.py
index 9a08752e..8dfb52fb 100644
--- a/icechunk-python/python/icechunk/store.py
+++ b/icechunk-python/python/icechunk/store.py
@@ -254,6 +254,25 @@ def set_virtual_refs(
         *,
         validate_containers: bool = False,
     ) -> list[tuple[int, ...]] | None:
+        """Store multiple virtual references for the same array.
+
+        Parameters
+        ----------
+        array_path : str
+            The path to the array inside the Zarr store. Example: "/groupA/groupB/outputs/my-array"
+        chunks : list[VirtualChunkSpec],
+            The list of virtula chunks to add
+        validate_containers: bool
+            If set to true, ignore virtual references for locations that don't match any existing virtual chunk container
+
+
+        Returns
+        -------
+        list[tuple[int, ...]] | None
+
+            If all virtual references where successfully updated, it returns None.
+            If there were validation errors, it returns the chunk indices of all failed references.
+        """
         return self._store.set_virtual_refs(array_path, chunks, validate_containers)
 
     async def delete(self, key: str) -> None: