feat: refresh cached MCP tool schema before call

[radugheo]

• Cached MCP discovery mode fetches the live tool schema before each call when refresh_schema_before_call is enabled (default true); when disabled, the cached snapshot is used as-is.
• On a breaking schema change (a newly required parameter, a dropped or renamed parameter, or a type change), the tool is not executed: its bound schema is refreshed and the model is asked to retry against the live schema. Non-breaking or cosmetic changes proceed against the cached schema.
• Falls back to the cached schema if the live schema cannot be fetched or the tool is missing on the server.
• Reads the flag defensively so the runtime works across uipath versions that predate the typed field.
• Bumps version to 0.12.4.
• Adds tests and updates module docs.

Tested live (DeepWiki MCP) across all discovery modes:

• cached + refresh self-heals on a breaking schema change (the model retries against the live schema)
• cached without refresh fails on the same drift
• cached with a matching snapshot is unaffected
• dynamic all and dynamic subset behave as expected

Related PRs:

• uipath-python: feat: add refreshSchemaBeforeCall to cached MCP tools config uipath-python#1730
• Agents: https://github.com/UiPath/Agents/pull/5593
• uipath-agents-python: https://github.com/UiPath/uipath-agents-python/pull/545

Development Package

• Use uipath pack --nolock to get the latest dev build from this PR (requires version range).
• Add this package as a dependency in your pyproject.toml:

[project]
dependencies = [
  # Exact version:
  "uipath-langchain==0.12.4.dev1009154951",

  # Any version from PR
  "uipath-langchain>=0.12.4.dev1009150000,<0.12.4.dev1009160000"
]

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.uv.sources]
uipath-langchain = { index = "testpypi" }

[tool.uv]
override-dependencies = [
    "uipath-langchain>=0.12.4.dev1009150000,<0.12.4.dev1009160000",
]

[Copilot]

Pull request overview

This PR enhances MCP cached discovery mode by optionally refreshing the live tool schema from the server immediately before each tool invocation, improving resilience when server-side tool contracts change while still planning from the cached snapshot.

Changes:

• Added per-call schema refresh for cached discovery mode via a refresh_schema_before_call flag (defaulting to enabled in cached mode) with best-effort fallback behavior.
• Extended MCP tool creation/invocation tests to cover refresh ordering, disabling the refresh, and graceful fallback scenarios.
• Bumped package version to 0.12.1 and updated module/test documentation accordingly.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/uipath_langchain/agent/tools/mcp/mcp_tool.py	Implements cached-mode per-call list_tools() refresh logic and defensive flag reading for backward compatibility.
tests/agent/tools/test_mcp/test_mcp_tool.py	Adds focused async tests validating refresh behavior, ordering, and fallback paths.
src/uipath_langchain/agent/tools/mcp/claude.md	Documents cached mode behavior, defaults, and the rationale for per-call refresh.
tests/agent/tools/test_mcp/claude.md	Updates test module documentation to include the new test class and coverage summary.
pyproject.toml	Version bump to 0.12.1.
uv.lock	Lockfile updated to reflect the new package version.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud