From 328ef528652d39777a885093749c60dde590196d Mon Sep 17 00:00:00 2001
From: Christopher Hertel <mail@christopher-hertel.de>
Date: Thu, 8 Oct 2026 01:09:24 +0200
Subject: [PATCH 1/2] [Docs] Throw ToolCallException in the first tool example
 and add builder defaults

---
 docs/run/server-builder.md | 4 ++++
 docs/servers/tools.md      | 5 +++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/run/server-builder.md b/docs/run/server-builder.md
index 017d4a8d..cc73aec7 100644
--- a/docs/run/server-builder.md
+++ b/docs/run/server-builder.md
@@ -114,16 +114,20 @@ use Mcp\Server\Wire\CachePolicy;
 $server = Server::builder()
     // Signs the state a multi round-trip request carries through the client.
     // The same key must reach every process that might serve the retry.
+    // The key needs at least 32 bytes, otherwise build() throws. TTL in seconds, default 600.
+    // Without a key, the server refuses every state the client sends back.
     ->setRequestState($_ENV['MCP_REQUEST_STATE_KEY'], ttl: 600)
 
     // Bounds the input-required shim, which fulfils an `InputRequiredResult`
     // over a handshake-era connection. `withoutInputRequiredShim()` turns it off.
+    // Defaults to 8 rounds and a 600 second timeout per round.
     ->setInputRequiredLimits(maxRounds: 4, roundTimeout: 120)
 
     // Caching hints stamped on cacheable results. Defaults to `ttlMs: 0, private`.
     ->setCachePolicy(CachePolicy::default(30_000)->withMethod('tools/list', 3_600_000, CacheScope::Public))
 
     // Delivery for `subscriptions/listen`, and how long such a stream is held.
+    // The lifetime defaults to 30 seconds; 0 keeps the stream open until the client or the runtime ends it.
     ->setNotificationBus(new Psr16NotificationBus($cache))
     ->setSubscriptionLifetime(0)
 
diff --git a/docs/servers/tools.md b/docs/servers/tools.md
index 258039f3..ea56d45b 100644
--- a/docs/servers/tools.md
+++ b/docs/servers/tools.md
@@ -4,6 +4,7 @@ Tools are callable functions that perform actions and return results.
 
 ```php
 use Mcp\Capability\Attribute\McpTool;
+use Mcp\Exception\ToolCallException;
 
 class Calculator
 {
@@ -17,8 +18,8 @@ class Calculator
             'add' => $a + $b,
             'subtract' => $a - $b,
             'multiply' => $a * $b,
-            'divide' => $b != 0 ? $a / $b : throw new \InvalidArgumentException('Division by zero'),
-            default => throw new \InvalidArgumentException('Invalid operation')
+            'divide' => $b != 0 ? $a / $b : throw new ToolCallException('Division by zero'),
+            default => throw new ToolCallException('Invalid operation')
         };
     }
 }

From b314fa7a13c61c996dff5fd1ddb5db8432c647f1 Mon Sep 17 00:00:00 2001
From: Christopher Hertel <mail@christopher-hertel.de>
Date: Thu, 8 Oct 2026 01:49:35 +0200
Subject: [PATCH 2/2] [Docs] Apply the shim timeout to each input request

---
 docs/run/server-builder.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/run/server-builder.md b/docs/run/server-builder.md
index cc73aec7..c1337674 100644
--- a/docs/run/server-builder.md
+++ b/docs/run/server-builder.md
@@ -120,7 +120,7 @@ $server = Server::builder()
 
     // Bounds the input-required shim, which fulfils an `InputRequiredResult`
     // over a handshake-era connection. `withoutInputRequiredShim()` turns it off.
-    // Defaults to 8 rounds and a 600 second timeout per round.
+    // Defaults to 8 rounds and a 600 second timeout for each input request.
     ->setInputRequiredLimits(maxRounds: 4, roundTimeout: 120)
 
     // Caching hints stamped on cacheable results. Defaults to `ttlMs: 0, private`.