diff --git a/libs/core/langchain_core/language_models/model_profile.py b/libs/core/langchain_core/language_models/model_profile.py
index b556c0a6467..75524ad6e50 100644
--- a/libs/core/langchain_core/language_models/model_profile.py
+++ b/libs/core/langchain_core/language_models/model_profile.py
@@ -11,14 +11,20 @@ logger = logging.getLogger(__name__)
 
 
 class ModelProfile(TypedDict, total=False):
-    """Model profile.
+    """Description of a chat model's capabilities, exposed via `model.profile`.
+
+    See the
+    [model profiles guide](https://docs.langchain.com/oss/python/langchain/models#model-profiles)
+    for concepts and usage. Data is sourced from
+    [models.dev](https://github.com/sst/models.dev), augmented with additional
+    fields, and generated by the
+    [`langchain-model-profiles`](https://github.com/langchain-ai/langchain/tree/master/libs/model-profiles)
+    package (via its `langchain-profiles` CLI).
 
     !!! warning "Beta feature"
 
-        This is a beta feature. The format of model profiles is subject to change.
-
-    Provides information about chat model capabilities, such as context window sizes
-    and supported features.
+        Fields and format are subject to change. This is a `total=False`
+        `TypedDict`, so any field may be absent — guard accesses with `.get()`.
     """
 
     __pydantic_config__ = ConfigDict(extra="allow")  # type: ignore[misc]
@@ -26,10 +32,10 @@ class ModelProfile(TypedDict, total=False):
     # --- Model metadata ---
 
     name: str
-    """Human-readable model name."""
+    """Human-readable model name (e.g., `'GPT-5'`)."""
 
     status: str
-    """Model status (e.g., `'active'`, `'deprecated'`)."""
+    """Model lifecycle status (e.g., `'active'`, `'deprecated'`)."""
 
     release_date: str
     """Model release date (ISO 8601 format, e.g., `'2025-06-01'`)."""
@@ -43,7 +49,7 @@ class ModelProfile(TypedDict, total=False):
     # --- Input constraints ---
 
     max_input_tokens: int
-    """Maximum context window (tokens)"""
+    """Maximum context window (tokens)."""
 
     text_inputs: bool
     """Whether text inputs are supported."""
@@ -72,18 +78,18 @@ class ModelProfile(TypedDict, total=False):
     # TODO: add more detail about formats? e.g. bytes or base64
 
     image_tool_message: bool
-    """Whether images can be included in tool messages."""
+    """Whether images can be included in `ToolMessage` content."""
 
     pdf_tool_message: bool
-    """Whether PDFs can be included in tool messages."""
+    """Whether PDFs can be included in `ToolMessage` content."""
 
     # --- Output constraints ---
 
     max_output_tokens: int
-    """Maximum output tokens"""
+    """Maximum output tokens."""
 
     reasoning_output: bool
-    """Whether the model supports [reasoning / chain-of-thought](https://docs.langchain.com/oss/python/langchain/models#reasoning)"""
+    """Whether the model supports [reasoning / chain-of-thought](https://docs.langchain.com/oss/python/langchain/models#reasoning)."""
 
     text_outputs: bool
     """Whether text outputs are supported."""
@@ -102,15 +108,14 @@ class ModelProfile(TypedDict, total=False):
 
     # --- Tool calling ---
     tool_calling: bool
-    """Whether the model supports [tool calling](https://docs.langchain.com/oss/python/langchain/models#tool-calling)"""
+    """Whether the model supports [tool calling](https://docs.langchain.com/oss/python/langchain/models#tool-calling)."""
 
     tool_choice: bool
-    """Whether the model supports [tool choice](https://docs.langchain.com/oss/python/langchain/models#forcing-tool-calls)"""
+    """Whether the model supports [tool choice](https://docs.langchain.com/oss/python/langchain/models#forcing-tool-calls)."""
 
     # --- Structured output ---
     structured_output: bool
-    """Whether the model supports a native [structured output](https://docs.langchain.com/oss/python/langchain/models#structured-outputs)
-    feature"""
+    """Whether the model supports native [structured output](https://docs.langchain.com/oss/python/langchain/models#structured-outputs)."""
 
     # --- Other capabilities ---