diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index fb90efa1db..f5a9234f1e 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
 README.md: 20df93e734afb9e7f4280d3aa208af2c8338001c
-README.zh.md: d16a8a90c626c746b8629d148e432302f72b5f30
+README.zh.md: a9741673b7283a78223fb9523abef022a79638e4
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index d16a8a90c6..a9741673b7 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -145,7 +145,7 @@ agent loop 将连续的 `parallel` 调用归入有界滚动池，并把每个 `e
 
 #### 模型看到的内容
 
-Code Mode 会公开生成的 [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tools)、下方 SDK 说明，以及按所加载运行时语言生成的精确 SDK 块（TypeScript 的 `declare const tools` 块，或 Python 的 `tools` 声明）。`both` 会同时公开普通 schema 与此 Code Mode 接口。说明与 SDK 块随所加载运行时的语言切换；下方展示 TypeScript 风格（经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md)），Python 风格（用于任何报告 `language: 'python'` 的运行时）形状相同，只是换成 Python 语法（`await tools.name(args)`、异体名用下标访问、`print(...)` 与顶层 `return`）。
+Code Mode 会公开生成的 [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tools)、下方 SDK 说明，以及按所加载运行时语言生成的精确 SDK 块（TypeScript 的 `declare const tools` 块，或 Python 的 `tools` 声明）。`both` 会同时公开普通 schema 与此 Code Mode 接口。说明与 SDK 块随所加载运行时的语言切换；下方展示 TypeScript 风格（经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md)），Python 风格（用于任何报告 `language: 'python'` 的运行时）形状相同，只是换成 Python 语法（`await tools.name(args)`、特殊名称用下标访问、`print(...)` 与顶层 `return`）。
 
 ##### Code Mode SDK 说明
 
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index b0de1b7a0d..315afa5aa6 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -304,16 +304,20 @@ function childClassName(base: string, segment: string): string {
  *
  * A beyond-safe-range integral number takes `BigInt` digits rather than
  * `String`: Python integers are arbitrary-precision, so the emitted digits ARE
- * the value the model programs against, and `String` gives a different integer
- * than the double holds (`2 ** 60` prints the rounded `...847000`, not the
- * exact `...846976`) or no integer literal at all (`1e21` prints `1e+21`).
- * `String`'s rounding is not a bug in it: `Number::toString` is shortest
- * round-trip, so it emits the 16 digits that re-read to the same double and
- * pads with zeros, and those padded digits name an integer no double holds.
- * Passing one back would have to cross the argument boundary as a JSON number
- * — a double again — so the SDK would document a value no program can pass.
- * The TS flavor needs no counterpart: its literal is re-read by a JS parser
- * back into the same double.
+ * the value the model programs against, and `String` can give a different
+ * integer than the double holds (`2 ** 60` prints the rounded `...847000`, not
+ * the exact `...846976`) or no integer literal at all (`1e21` prints `1e+21`).
+ * `String`'s rounding is not a bug in it: `Number::toString` emits the shortest
+ * decimal string that re-reads to the same double, then pads to the exponent
+ * with zeros (1 significant digit for `1e20`, 16 for `2 ** 60`) — and when the
+ * shortest string is shorter than the double's exact value, those padded digits
+ * name an integer no double holds. Passing one back would have to cross the
+ * argument boundary as a JSON number — a double again — so the SDK would
+ * document a value no program can pass. `BigInt` needs no case split: where
+ * `String` is already exact (`2 ** 53`, `1e20`) the two agree byte for byte,
+ * and where it is not, `BigInt` is the exact one. The TS flavor needs no
+ * counterpart at all: its literal is re-read by a JS parser back into the same
+ * double.
  *
  * `JSON.stringify` is also what keeps this path's output parseable, and it is
  * the only thing that does. It covers both classes of hazard: the two kinds of