diff --git a/src/polymarket/models/clob/order_book.py b/src/polymarket/models/clob/order_book.py
index cb0e4c3..21b79a4 100644
--- a/src/polymarket/models/clob/order_book.py
+++ b/src/polymarket/models/clob/order_book.py
@@ -21,7 +21,9 @@ class OrderBook(BaseModel):
     token_id: TokenId = Field(validation_alias="asset_id")
     timestamp: datetime | None = None
     bids: tuple[OrderBookLevel, ...]
+    """Bid levels in ascending price order, lowest bid first."""
     asks: tuple[OrderBookLevel, ...]
+    """Ask levels in descending price order, highest ask first."""
     min_order_size: _DecimalFromString
     tick_size: _DecimalFromString
     neg_risk: bool
diff --git a/src/polymarket/streams/_specs.py b/src/polymarket/streams/_specs.py
index b1a8392..c264345 100644
--- a/src/polymarket/streams/_specs.py
+++ b/src/polymarket/streams/_specs.py
@@ -25,10 +25,16 @@
 
 @dataclass(frozen=True, slots=True, kw_only=True)
 class MarketSpec:
-    """Subscribe to realtime market updates for one or more token ids."""
+    """Subscribe to realtime market updates for one or more token ids.
+
+    Set ``custom_feature_enabled=True`` to additionally receive
+    ``MarketBestBidAskEvent``, ``NewMarketEvent``, and ``MarketResolvedEvent``.
+    """
 
     token_ids: Sequence[str]
+    """Token ids whose market events should be delivered."""
     custom_feature_enabled: bool = False
+    """Whether to enable top-of-book and market lifecycle events."""
     topic: Literal["market"] = field(default="market", init=False)
 
     def __post_init__(self) -> None: