diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index c7c74203..e187fedc 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -28,7 +28,10 @@
 
 logger = logging.getLogger(__name__)
 
-_DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024  # 1MB buffer limit
+# Default buffer size increased from 1MB to 10MB to accommodate modern MCP tools
+# that may return large responses (e.g., Puppeteer evaluate() with DOM data,
+# large file contents, etc.). Users can override via ClaudeAgentOptions.max_buffer_size
+_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024  # 10MB buffer limit
 MINIMUM_CLAUDE_CODE_VERSION = "2.0.0"
 
 # Platform-specific command line length limits
@@ -582,11 +585,22 @@ async def _read_messages_impl(self) -> AsyncIterator[dict[str, Any]]:
                     # Keep accumulating partial JSON until we can parse it
                     json_buffer += json_line
 
-                    if len(json_buffer) > self._max_buffer_size:
-                        buffer_length = len(json_buffer)
+                    buffer_length = len(json_buffer)
+
+                    # Warn when buffer reaches 80% capacity
+                    if buffer_length > self._max_buffer_size * 0.8 and buffer_length <= self._max_buffer_size:
+                        logger.warning(
+                            f"JSON buffer size ({buffer_length:,} bytes) is approaching the limit "
+                            f"({self._max_buffer_size:,} bytes). Consider increasing max_buffer_size "
+                            f"in ClaudeAgentOptions if you encounter buffer overflow errors."
+                        )
+
+                    if buffer_length > self._max_buffer_size:
                         json_buffer = ""
                         raise SDKJSONDecodeError(
-                            f"JSON message exceeded maximum buffer size of {self._max_buffer_size} bytes",
+                            f"JSON message exceeded maximum buffer size of {self._max_buffer_size:,} bytes. "
+                            f"Actual size: {buffer_length:,} bytes. "
+                            f"Increase max_buffer_size in ClaudeAgentOptions to handle larger responses.",
                             ValueError(
                                 f"Buffer size {buffer_length} exceeds limit {self._max_buffer_size}"
                             ),
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index fa6ca352..44487ab2 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -639,7 +639,9 @@ class ClaudeAgentOptions:
     extra_args: dict[str, str | None] = field(
         default_factory=dict
     )  # Pass arbitrary CLI flags
-    max_buffer_size: int | None = None  # Max bytes when buffering CLI stdout
+    max_buffer_size: int | None = None  # Max bytes when buffering CLI stdout (default: 10MB).
+    # Increase this if you use MCP tools that return large responses (e.g., Puppeteer with DOM extraction,
+    # large file contents). Example: max_buffer_size=20*1024*1024 for 20MB limit.
     debug_stderr: Any = (
         sys.stderr
     )  # Deprecated: File-like object for debug output. Use stderr callback instead.