docs: refresh pdf tool model fallback refs

Author: steipete

docs/concepts/models.md

@@ -26,6 +26,9 @@ Related:
 
 - `agents.defaults.models` is the allowlist/catalog of models OpenClaw can use (plus aliases).
 - `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
+- `agents.defaults.pdfModel` is used by the `pdf` tool. If omitted, the tool
+  falls back to `agents.defaults.imageModel`, then the resolved session/default
+  model.
 - `agents.defaults.imageGenerationModel` is used by the shared image-generation capability. If omitted, `image_generate` can still infer a provider default from compatible auth-backed image-generation plugins. If you set a specific provider/model, also configure that provider's auth/API key.
 - Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)).
 
@@ -50,6 +53,7 @@ subscription** (OAuth) and **Anthropic** (API key or Claude CLI).
 
 - `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`
 - `agents.defaults.imageModel.primary` and `agents.defaults.imageModel.fallbacks`
+- `agents.defaults.pdfModel.primary` and `agents.defaults.pdfModel.fallbacks`
 - `agents.defaults.imageGenerationModel.primary` and `agents.defaults.imageGenerationModel.fallbacks`
 - `agents.defaults.models` (allowlist + aliases + provider params)
 - `models.providers` (custom providers written into `models.json`)

docs/tools/pdf.md

@@ -23,10 +23,20 @@ The tool is only registered when OpenClaw can resolve a PDF-capable model config
 
 1. `agents.defaults.pdfModel`
 2. fallback to `agents.defaults.imageModel`
-3. fallback to best effort provider defaults based on available auth
+3. fallback to the agent's resolved session/default model
+4. if native-PDF providers are auth-backed, prefer them ahead of generic image fallback candidates
 
 If no usable model can be resolved, the `pdf` tool is not exposed.
 
+Availability notes:
+
+- The fallback chain is auth-aware. A configured `provider/model` only counts if
+  OpenClaw can actually authenticate that provider for the agent.
+- Native PDF providers are currently **Anthropic** and **Google**.
+- If the resolved session/default provider already has a configured vision/PDF
+  model, the PDF tool reuses that before falling back to other auth-backed
+  providers.
+
 ## Input reference
 
 - `pdf` (`string`): one PDF path or URL
@@ -65,6 +75,8 @@ The tool sends raw PDF bytes directly to provider APIs.
 Native mode limits:
 
 - `pages` is not supported. If set, the tool returns an error.
+- Multi-PDF input is supported; each PDF is sent as a native document block /
+  inline PDF part before the prompt.
 
 ### Extraction fallback mode
 
@@ -80,6 +92,9 @@ Fallback details:
 
 - Page image extraction uses a pixel budget of `4,000,000`.
 - If the target model does not support image input and there is no extractable text, the tool errors.
+- If text extraction succeeds but image extraction would require vision on a
+  text-only model, OpenClaw drops the rendered images and continues with the
+  extracted text.
 - Extraction fallback requires `pdfjs-dist` (and `@napi-rs/canvas` for image rendering).
 
 ## Config