langchain-tool-args-validation-middleware 0.1.0__tar.gz

langchain_tool_args_validation_middleware-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Publish
+
+# Publish a new release whenever a version tag (e.g. v0.2.0) is pushed.
+# Flow: build once -> publish to TestPyPI -> publish to PyPI.
+# Authentication uses PyPI Trusted Publishing (OIDC); no API tokens/secrets.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# No permissions by default; each job opts into exactly what it needs.
+permissions: {}
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv version --short --no-sync)"
+          echo "tag=$tag pyproject=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $pkg. Bump the version before tagging."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Publish to TestPyPI
+        run: >-
+          uv publish
+          --trusted-publishing always
+          --publish-url https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish to PyPI
+    needs: testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

langchain_tool_args_validation_middleware-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/

langchain_tool_args_validation_middleware-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_tool_args_validation_middleware-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: langchain-tool-args-validation-middleware
+Version: 0.1.0
+Summary: LangChain agent middleware that validates LLM-generated tool-call arguments against each tool's schema before tool execution / HITL.
+Project-URL: Homepage, https://github.com/Serjbory/langchain-tool-args-validation-middleware
+Project-URL: Repository, https://github.com/Serjbory/langchain-tool-args-validation-middleware
+Author: Serj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langchain,mcp,middleware,tools,validation
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain>=1.0.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: jsonschema
+Requires-Dist: jsonschema>=4.0; extra == 'jsonschema'
+Provides-Extra: test
+Requires-Dist: jsonschema>=4.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-tool-args-validation-middleware
+
+A LangChain agent middleware that validates LLM-generated **tool-call arguments**
+against each tool's schema **before** the tool runs (and before any
+human-in-the-loop approval step). When arguments are invalid it appends error
+`ToolMessage`s and re-invokes the model so it can self-correct — all inside the
+model node, so only the final valid `AIMessage` ever enters the graph state.
+
+```bash
+pip install langchain-tool-args-validation-middleware            # Pydantic tools only
+pip install "langchain-tool-args-validation-middleware[jsonschema]"  # + MCP / dict-schema tools
+```
+
+## Why
+
+LLMs frequently emit malformed tool calls: missing required fields, wrong types,
+hallucinated empty values, or extra keys. Without validation those reach the
+tool node and cause runtime errors or silent corruption — and in
+human-in-the-loop workflows, a human is asked to approve obviously-broken
+arguments. Catching this at the model boundary lets the agent fix itself in one
+extra model call instead of a full agent-loop iteration.
+
+It complements, rather than replaces, `ToolRetryMiddleware` (retries on tool
+*exceptions*) and `ModelRetryMiddleware` (retries on model *exceptions*): this
+one retries on *schema violations*, before execution.
+
+![Trace showing the middleware catching an invalid tool call and prompting the model to self-correct](https://raw.githubusercontent.com/Serjbory/langchain-tool-args-validation-middleware/main/docs/images/trace-example.jpg)
+
+*A trace of `create_oos_alert`: the model emitted arguments that violate the
+schema, the middleware rejected them with a precise error and a corrective hint,
+and the model retried — all inside the model node, before the tool ran.*
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+from langchain_tool_args_validation_middleware import ToolArgsValidationMiddleware
+
+agent = create_agent(
+    model,
+    tools=tools,
+    middleware=[ToolArgsValidationMiddleware()],  # resolves schemas from the agent's tools
+)
+```
+
+Both validation paths are supported automatically:
+
+- **Pydantic tools** (`@tool`, or any tool with a `BaseModel` `args_schema`) →
+  validated with `BaseModel.model_validate`.
+- **MCP / dict-schema tools** (`args_schema` is a raw JSON Schema `dict`) →
+  validated with `jsonschema` (soft dependency, `Draft7Validator` by default).
+
+Unknown tools (no resolvable schema) pass through unvalidated.
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `tools` | `None` | Explicit tool list. If omitted, schemas are resolved lazily from `request.tools` and cached by tool-name set (handles dynamic toolsets). |
+| `max_retries` | `2` | Validation-retry cycles per model invocation (up to `max_retries + 1` model calls). |
+| `strip_empty_values` | `True` | Recursively drop `None` / `{}` / `[]` before validation. |
+| `strip_placeholder_strings` | `False` | Also drop placeholder strings like `"null"`. Off by default — see below. |
+| `placeholder_strings` | conservative set | Set used when string stripping is enabled. |
+| `json_schema_validator_class` | `None` | Override the JSON Schema validator class. `None` → lazy `Draft7Validator`. |
+| `extra_validators` | `None` | Extra `(name, args) -> list[str]` checks for domain rules. |
+| `on_failure` | `"pass"` | After retries are exhausted: `"pass"` (fail open) or `"raise"`. |
+
+## Design decisions for the two thorniest cases
+
+### Batch (partial) failure
+
+Providers (Anthropic, Gemini, OpenAI) require that **every** `tool_call` in an
+assistant message receive a matching `ToolMessage` before the next turn. So when
+a multi-call turn has *any* invalid call, the middleware emits:
+
+- an **error** `ToolMessage` for each invalid call, and
+- a **"not executed"** notice for each *valid* sibling call (it hasn't run yet —
+  we're still inside the model node — so it can't have a real result), asking the
+  model to re-issue the whole batch with corrected arguments.
+
+The failed `AIMessage` is placed before these `ToolMessage`s, and failed turns
+accumulate across retries so the model sees its repeated mistakes.
+
+### `strip_empty_values` and the write-back contract
+
+LLMs (Gemini especially) emit explicit `null`/`{}`/`[]` for optional fields
+instead of omitting them, causing needless validation failures. When stripping
+is on, the **cleaned arguments replace the originals on the tool call**, so what
+we validate is exactly what executes — no soundness gap between validation and
+execution.
+
+The trade-off: stripping a value that is *meaningfully empty* (e.g. `tags: []`
+meaning "clear all tags", or `null` meaning "explicitly unset") changes
+behaviour. Container stripping (`None`/`{}`/`[]`) is on by default because it's
+usually safe. **String-placeholder stripping is opt-in only** — tokens like
+`"NA"` (Namibia's ISO code) are legitimate values and must never be dropped
+silently. Enable it deliberately with `strip_placeholder_strings=True` and a set
+you control.
+
+### Fail-open
+
+After `max_retries`, the default `on_failure="pass"` returns the last response
+unchanged — the (still-invalid) args reach the tool node, where normal tool
+error handling takes over. This makes the middleware best-effort
+self-correction, not a hard guarantee. Use `on_failure="raise"` if you'd rather
+surface a `ToolArgsValidationError`.
+
+## Extra validators
+
+Plug in domain rules without touching core behaviour. A bundled example flags
+LangChain internal message IDs (`lc_<uuid>`) that LLMs sometimes mistake for
+real data identifiers:
+
+```python
+from langchain_tool_args_validation_middleware import detect_langchain_internal_ids
+
+ToolArgsValidationMiddleware(extra_validators=[detect_langchain_internal_ids])
+```
+
+## License
+
+MIT

langchain_tool_args_validation_middleware-0.1.0/README.md

@@ -0,0 +1,122 @@
+# langchain-tool-args-validation-middleware
+
+A LangChain agent middleware that validates LLM-generated **tool-call arguments**
+against each tool's schema **before** the tool runs (and before any
+human-in-the-loop approval step). When arguments are invalid it appends error
+`ToolMessage`s and re-invokes the model so it can self-correct — all inside the
+model node, so only the final valid `AIMessage` ever enters the graph state.
+
+```bash
+pip install langchain-tool-args-validation-middleware            # Pydantic tools only
+pip install "langchain-tool-args-validation-middleware[jsonschema]"  # + MCP / dict-schema tools
+```
+
+## Why
+
+LLMs frequently emit malformed tool calls: missing required fields, wrong types,
+hallucinated empty values, or extra keys. Without validation those reach the
+tool node and cause runtime errors or silent corruption — and in
+human-in-the-loop workflows, a human is asked to approve obviously-broken
+arguments. Catching this at the model boundary lets the agent fix itself in one
+extra model call instead of a full agent-loop iteration.
+
+It complements, rather than replaces, `ToolRetryMiddleware` (retries on tool
+*exceptions*) and `ModelRetryMiddleware` (retries on model *exceptions*): this
+one retries on *schema violations*, before execution.
+
+![Trace showing the middleware catching an invalid tool call and prompting the model to self-correct](https://raw.githubusercontent.com/Serjbory/langchain-tool-args-validation-middleware/main/docs/images/trace-example.jpg)
+
+*A trace of `create_oos_alert`: the model emitted arguments that violate the
+schema, the middleware rejected them with a precise error and a corrective hint,
+and the model retried — all inside the model node, before the tool ran.*
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+from langchain_tool_args_validation_middleware import ToolArgsValidationMiddleware
+
+agent = create_agent(
+    model,
+    tools=tools,
+    middleware=[ToolArgsValidationMiddleware()],  # resolves schemas from the agent's tools
+)
+```
+
+Both validation paths are supported automatically:
+
+- **Pydantic tools** (`@tool`, or any tool with a `BaseModel` `args_schema`) →
+  validated with `BaseModel.model_validate`.
+- **MCP / dict-schema tools** (`args_schema` is a raw JSON Schema `dict`) →
+  validated with `jsonschema` (soft dependency, `Draft7Validator` by default).
+
+Unknown tools (no resolvable schema) pass through unvalidated.
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `tools` | `None` | Explicit tool list. If omitted, schemas are resolved lazily from `request.tools` and cached by tool-name set (handles dynamic toolsets). |
+| `max_retries` | `2` | Validation-retry cycles per model invocation (up to `max_retries + 1` model calls). |
+| `strip_empty_values` | `True` | Recursively drop `None` / `{}` / `[]` before validation. |
+| `strip_placeholder_strings` | `False` | Also drop placeholder strings like `"null"`. Off by default — see below. |
+| `placeholder_strings` | conservative set | Set used when string stripping is enabled. |
+| `json_schema_validator_class` | `None` | Override the JSON Schema validator class. `None` → lazy `Draft7Validator`. |
+| `extra_validators` | `None` | Extra `(name, args) -> list[str]` checks for domain rules. |
+| `on_failure` | `"pass"` | After retries are exhausted: `"pass"` (fail open) or `"raise"`. |
+
+## Design decisions for the two thorniest cases
+
+### Batch (partial) failure
+
+Providers (Anthropic, Gemini, OpenAI) require that **every** `tool_call` in an
+assistant message receive a matching `ToolMessage` before the next turn. So when
+a multi-call turn has *any* invalid call, the middleware emits:
+
+- an **error** `ToolMessage` for each invalid call, and
+- a **"not executed"** notice for each *valid* sibling call (it hasn't run yet —
+  we're still inside the model node — so it can't have a real result), asking the
+  model to re-issue the whole batch with corrected arguments.
+
+The failed `AIMessage` is placed before these `ToolMessage`s, and failed turns
+accumulate across retries so the model sees its repeated mistakes.
+
+### `strip_empty_values` and the write-back contract
+
+LLMs (Gemini especially) emit explicit `null`/`{}`/`[]` for optional fields
+instead of omitting them, causing needless validation failures. When stripping
+is on, the **cleaned arguments replace the originals on the tool call**, so what
+we validate is exactly what executes — no soundness gap between validation and
+execution.
+
+The trade-off: stripping a value that is *meaningfully empty* (e.g. `tags: []`
+meaning "clear all tags", or `null` meaning "explicitly unset") changes
+behaviour. Container stripping (`None`/`{}`/`[]`) is on by default because it's
+usually safe. **String-placeholder stripping is opt-in only** — tokens like
+`"NA"` (Namibia's ISO code) are legitimate values and must never be dropped
+silently. Enable it deliberately with `strip_placeholder_strings=True` and a set
+you control.
+
+### Fail-open
+
+After `max_retries`, the default `on_failure="pass"` returns the last response
+unchanged — the (still-invalid) args reach the tool node, where normal tool
+error handling takes over. This makes the middleware best-effort
+self-correction, not a hard guarantee. Use `on_failure="raise"` if you'd rather
+surface a `ToolArgsValidationError`.
+
+## Extra validators
+
+Plug in domain rules without touching core behaviour. A bundled example flags
+LangChain internal message IDs (`lc_<uuid>`) that LLMs sometimes mistake for
+real data identifiers:
+
+```python
+from langchain_tool_args_validation_middleware import detect_langchain_internal_ids
+
+ToolArgsValidationMiddleware(extra_validators=[detect_langchain_internal_ids])
+```
+
+## License
+
+MIT

langchain_tool_args_validation_middleware-0.1.0/justfile

@@ -0,0 +1,72 @@
+# Run with: just <task-name>
+# Install just on mac: brew install just
+# Install just if not present on linux (Debian based)
+# curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+# To format justfile: just --fmt --unstable
+
+# Variables
+src_dir := "src/langchain_tool_args_validation_middleware"
+
+# Default recipe to display available commands
+default:
+    @just --list
+
+# Sync dependencies (including dev extras)
+sync:
+    uv sync --extra dev
+
+# Auto-format code
+format:
+    uv run --extra dev ruff check --select I --fix .
+    uv run --extra dev ruff format .
+
+# Lint and format check
+lint:
+    uv run --extra dev ruff format --check --diff .
+    uv run --extra dev ruff check --show-fixes .
+    uv run --extra dev mypy {{ src_dir }}
+
+# Run unit tests (optional path to narrow scope, e.g. just test tests/test_validation.py)
+test path="tests":
+    uv run --extra dev pytest --cov={{ src_dir }} {{ path }}
+
+# Run format, lint, and tests to check everything before committing
+pre-commit: format lint test
+
+# Build sdist and wheel into dist/
+build:
+    rm -rf dist
+    uv build
+
+# Publish to TestPyPI (local: uses UV_PUBLISH_TOKEN / ~/.pypirc; CI uses trusted publishing)
+publish-test: build
+    uv publish --publish-url https://test.pypi.org/legacy/
+
+# Publish to PyPI
+publish: build
+    uv publish
+
+# Bump version (just bump patch|minor|major|rc), commit, and tag
+bump level="patch":
+    uv version --bump {{ level }}
+    git commit -am "release: v$(uv version --short)"
+    git tag "v$(uv version --short)"
+    @echo "Pushed nothing yet. Run: git push && git push --tags"
+
+# Clean up cache files
+clean:
+    find . -type d -name "__pycache__" -exec rm -rf {} + && \
+    find . -type f -name "*.pyc" -delete && \
+    rm -rf .pytest_cache .coverage htmlcov .mypy_cache .ruff_cache
+
+# Install just if not present on mac
+install-just-on-mac:
+    @command -v just >/dev/null 2>&1 || { echo "Installing just..."; brew install just; }
+
+# Install uv if not present
+install-uv:
+    @command -v uv >/dev/null 2>&1 || { echo "Installing uv..."; curl -LsSf https://astral.sh/uv/install.sh | sh; }
+
+install-tools:
+    uv tool install ruff==0.15.11 --force
+    uv tool install mypy==1.18.2 --force

langchain_tool_args_validation_middleware-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-tool-args-validation-middleware"
+version = "0.1.0"
+description = "LangChain agent middleware that validates LLM-generated tool-call arguments against each tool's schema before tool execution / HITL."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Serj" }]
+keywords = ["langchain", "agents", "middleware", "tools", "validation", "mcp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "langchain>=1.0.0",
+    "langchain-core>=0.3.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+# jsonschema is a *soft* dependency: only needed when validating tools whose
+# args_schema is a raw JSON Schema dict (e.g. MCP tools).
+jsonschema = ["jsonschema>=4.0"]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "jsonschema>=4.0",
+]
+dev = [
+    "ruff",
+    "mypy",
+    "langchain-tool-args-validation-middleware[test]",
+]
+
+[project.urls]
+Homepage = "https://github.com/Serjbory/langchain-tool-args-validation-middleware"
+Repository = "https://github.com/Serjbory/langchain-tool-args-validation-middleware"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_tool_args_validation_middleware"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+
+# jsonschema is a soft dependency and ships no type stubs.
+[[tool.mypy.overrides]]
+module = ["jsonschema", "jsonschema.*"]
+ignore_missing_imports = true

langchain_tool_args_validation_middleware-0.1.0/src/langchain_tool_args_validation_middleware/__init__.py

@@ -0,0 +1,24 @@
+"""Validate LLM tool-call arguments against each tool's schema before execution."""
+
+from ._strip import DEFAULT_PLACEHOLDER_STRINGS, strip_empty
+from ._validation import ValidationIssue
+from .extras import detect_langchain_internal_ids
+from .middleware import (
+    ExtraValidator,
+    OnFailure,
+    ToolArgsValidationError,
+    ToolArgsValidationMiddleware,
+)
+
+__all__ = [
+    "DEFAULT_PLACEHOLDER_STRINGS",
+    "ExtraValidator",
+    "OnFailure",
+    "ToolArgsValidationError",
+    "ToolArgsValidationMiddleware",
+    "ValidationIssue",
+    "detect_langchain_internal_ids",
+    "strip_empty",
+]
+
+__version__ = "0.1.0"

langchain_tool_args_validation_middleware-0.1.0/src/langchain_tool_args_validation_middleware/_strip.py

@@ -0,0 +1,82 @@
+"""Recursive stripping of "empty" values from LLM-generated tool arguments.
+
+LLMs (Gemini especially) routinely emit explicit ``null`` or empty containers
+for optional fields instead of omitting them. Stripping these before validation
+avoids unnecessary retries: an optional field simply becomes absent, and a
+required field surfaces a clear ``'<field>' is a required property`` error.
+
+Design note — write-back contract
+----------------------------------
+When stripping is enabled the *cleaned* arguments replace the originals in the
+tool call, so the cleaned version is what both validation **and tool execution**
+see. This keeps "what we validated" and "what runs" identical (no soundness
+gap), at the cost of mutating the model's output. That trade-off is the whole
+point of stripping, but it means stripping a value that is *semantically
+meaningful* (e.g. ``tags: []`` meaning "clear all tags", or ``null`` meaning
+"explicitly unset") changes behaviour. Container stripping (``None``/``{}``/
+``[]``) is on by default; the far riskier string-placeholder stripping
+(``"none"``, ``"N/A"``, ...) is **opt-in only**, because tokens like ``"NA"``
+are legitimate values (Namibia's ISO code, "North America", ...).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# A conservative, opt-in default set of placeholder strings. Deliberately
+# excludes ambiguous real-world tokens like "na"/"nil". Callers may pass their
+# own set instead. Only used when string stripping is explicitly enabled.
+DEFAULT_PLACEHOLDER_STRINGS: frozenset[str] = frozenset(
+    {"none", "null", "undefined", '""', "''"}
+)
+
+
+def strip_empty(
+    value: Any,
+    *,
+    placeholder_strings: frozenset[str] | None = None,
+) -> Any:
+    """Return a copy of *value* with "empty" entries recursively removed.
+
+    Parameters
+    ----------
+    value:
+        The value to clean (typically a tool call's ``args`` dict, but works on
+        any nested dict/list structure).
+    placeholder_strings:
+        If provided, string values whose stripped/lower-cased form is in this
+        set are also removed. ``None`` (the default) disables string stripping
+        entirely — only ``None``/``{}``/``[]`` are removed.
+
+    Notes
+    -----
+    Returns a new structure; it never mutates *value* in place. The caller
+    decides whether to write the result back onto the tool call.
+    """
+    if isinstance(value, dict):
+        cleaned: dict[Any, Any] = {}
+        for key, val in value.items():
+            if _is_empty(val, placeholder_strings):
+                continue
+            cleaned[key] = strip_empty(val, placeholder_strings=placeholder_strings)
+        return cleaned
+    if isinstance(value, list):
+        return [
+            strip_empty(item, placeholder_strings=placeholder_strings)
+            for item in value
+            if not _is_empty(item, placeholder_strings)
+        ]
+    return value
+
+
+def _is_empty(value: Any, placeholder_strings: frozenset[str] | None) -> bool:
+    """Whether *value* should be dropped during stripping."""
+    if value is None:
+        return True
+    if value == {} or value == []:
+        return True
+    return (
+        placeholder_strings is not None
+        and isinstance(value, str)
+        and value.strip().lower() in placeholder_strings
+    )