fix(cache): sort MCP tools deterministically to stabilize prompt cache by bcherny · Pull Request #58037 · openclaw/openclaw

bcherny · 2026-03-31T01:10:38Z

Problem

createBundleMcpToolRuntime (src/agents/pi-bundle-mcp-tools.ts:122) is called on every turn from attempt.ts:1842. It collects tools via client.listTools() without sorting, then returns them in collection order.

The MCP spec doesn't guarantee listTools() order. If tool order differs between turns — from paginated responses, third-party server implementations, or future SDK changes — the tools array in the API request changes, busting the prompt cache at the tools block.

Fix

Sort the collected tools alphabetically by name before returning:

tools: tools.toSorted((a, b) => a.name.localeCompare(b.name))

This makes the tools block deterministic regardless of listTools() iteration order or server-config iteration order.

Semantics unchanged: collision resolution (first-server-wins via reservedNames set) happens during collection, before the sort.

Verification

Added regression test with a multi-tool server that registers zeta, alpha, mu — asserts runtime returns [alpha, mu, zeta]
All 4 tests pass
Lint clean
Checked downstream: all tool lookups in attempt.ts are name-based (allowlist, prefix-stripping at :620), not position-based

Follow-up (not in this PR)

Hoist runtime to session scope. createBundleMcpToolRuntime currently spawns stdio transports + listTools() on every turn and disposes in the finally at attempt.ts:3227. Bigger win: cache the runtime keyed on a hash of loaded.mcpServers config, dispose on session end. Stops re-spawning MCP servers per turn. More invasive — needs session-lifecycle wiring.

🤖 Generated with Claude Code

greptile-apps · 2026-03-31T01:12:38Z

Greptile Summary

This PR makes the tools array returned by createBundleMcpToolRuntime stable across turns by sorting tools alphabetically by name before returning them. The fix prevents prompt-cache busting caused by non-deterministic listTools() ordering from the MCP SDK or third-party servers.

The one-line change (tools.toSorted(...)) is applied after all collision-deduplication logic, so first-server-wins semantics are preserved.
Array.prototype.toSorted is available on Node.js ≥ 20 — the project's minimum engine is >=22.14.0, so there is no compatibility concern.
A new integration test spins up a real MCP server that registers tools in zeta → alpha → mu order and asserts the runtime returns [alpha, mu, zeta], giving direct regression coverage for the fix.
The writeExecutable helper imported from the test harness was already exported there; the import is consistent with the existing test pattern.
Overall: a minimal, correct, well-tested fix with no semantic side-effects.

Confidence Score: 5/5

Safe to merge — minimal, correct change with direct regression test coverage and no semantic side-effects.
The fix is a single non-mutating sort applied at the right place in the pipeline. Node.js ≥ 22.14.0 is required (toSorted available since Node 20). No P1 or P0 issues found; all remaining observations are informational.
No files require special attention.

_{Reviews (1): Last reviewed commit: "fix(cache): sort MCP tools deterministic..." | Re-trigger Greptile}

@bcherny

openclaw#58037) (thanks @bcherny)

odysseus0 · 2026-04-04T00:20:15Z

Landed via manual rebase-port onto main (original base was stale after upstream MCP runtime refactor).

Ported sort fix to materializeBundleMcpToolsForRun in src/agents/pi-bundle-mcp-materialize.ts
Added sort-order test to src/agents/pi-bundle-mcp-tools.materialize.test.ts
Land commit: 2ca9eed
Merge commit:

Thanks @bcherny!

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038

(#60633) * docs: correct overstated prompt-cache comments from #58036 #58037 #58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

…#2497) MCP's `list_tools()` does not guarantee tool ordering. If tool order differs between turns — from paginated responses, server restarts, or SDK changes — the tools array in the API request changes, busting the prompt cache at the tools block. Sort the collected tools by name in `_load_tools_from_config` to make the tools block deterministic. Inspired by [openclaw/openclaw#58037](openclaw/openclaw#58037).

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038 (openclaw#60633) * docs: correct overstated prompt-cache comments from openclaw#58036 openclaw#58037 openclaw#58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

…langchain-ai#2497) MCP's `list_tools()` does not guarantee tool ordering. If tool order differs between turns — from paginated responses, server restarts, or SDK changes — the tools array in the API request changes, busting the prompt cache at the tools block. Sort the collected tools by name in `_load_tools_from_config` to make the tools block deterministic. Inspired by [openclaw/openclaw#58037](openclaw/openclaw#58037).

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038 (openclaw#60633) * docs: correct overstated prompt-cache comments from openclaw#58036 openclaw#58037 openclaw#58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038 (openclaw#60633) * docs: correct overstated prompt-cache comments from openclaw#58036 openclaw#58037 openclaw#58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038 (openclaw#60633) * docs: correct overstated prompt-cache comments from openclaw#58036 openclaw#58037 openclaw#58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

…enclaw#58037 openclaw#58038 (openclaw#60633) * docs: correct overstated prompt-cache comments from openclaw#58036 openclaw#58037 openclaw#58038 * docs: restore purpose context in MCP tool sort comment * docs: drop misleading 'legacy' framing from image-prune comments * docs: restore useful context stripped from image-prune comments * docs: restore 'deterministically' in MCP tool sort comment * docs: restore 'idempotent' at attempt.ts callsite * docs: restore 'provider prompt cache' in context-guard comment

openclaw-barnacle Bot added agents Agent runtime and tooling size: S labels Mar 31, 2026

This comment was marked as spam.

Sign in to view

odysseus0 self-assigned this Apr 4, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

2ca9eed

openclaw#58037) (thanks @bcherny)

odysseus0 force-pushed the cache/mcp-tools-sort branch from e134420 to 2ca9eed Compare April 4, 2026 00:19

odysseus0 merged commit bc16b9d into openclaw:main Apr 4, 2026
3 checks passed

github-actions Bot mentioned this pull request Apr 4, 2026

📡 Upstream Digest — 2026-04-04 01:24 UTC curtismercier/openclaw-mods#459

Open

MonkeyLeeT mentioned this pull request Apr 4, 2026

docs: correct overstated prompt-cache comments from #58036 #58037 #58038 #60633

Merged

1 task

This was referenced Apr 4, 2026

fix(cache): improve Anthropic prompt cache hit rate with system split and tool stability anomalyco/opencode#14743

Open

GH#17059: add cache-health command to observability-helper marcusquinn/aidevops#17063

Merged

KimGLee pushed a commit to KimGLee/openclaw that referenced this pull request Apr 4, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

443c390

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

affsantos mentioned this pull request Apr 4, 2026

fix(cache): enable prompt cache retention for Anthropic Vertex AI #60888

Merged

27 tasks

MonkeyLeeT added a commit to MonkeyLeeT/openclaw that referenced this pull request Apr 4, 2026

docs: correct overstated prompt-cache comments from openclaw#58036 op…

6c459f6

…enclaw#58037 openclaw#58038

github-actions Bot mentioned this pull request Apr 6, 2026

Update ghcr.io/openclaw/openclaw Docker tag to v2026.4.8 claytono/infra#1923

Merged

1 task

mdrxy mentioned this pull request Apr 7, 2026

fix(cli): sort MCP tools deterministically for prompt-cache stability langchain-ai/deepagents#2497

Merged

ibetitsmike mentioned this pull request Apr 7, 2026

🤖 perf: sort tools deterministically for prompt cache stability coder/mux#3145

Merged

liu51115 mentioned this pull request Apr 8, 2026

[Bug] Compaction invalidates provider prompt cache prefix Martian-Engineering/lossless-claw#324

Closed

lovewanwan pushed a commit to lovewanwan/openclaw that referenced this pull request Apr 28, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

70e48e2

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

ogt-redknie pushed a commit to ogt-redknie/OPENX that referenced this pull request May 2, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

541c801

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

ashvinnagarajan mentioned this pull request May 7, 2026

fix(cache): emit tools before input in OpenAI Responses request body for prefix-cache stability #78747

Open

12 tasks

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

183fc46

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

a2d6671

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

Nachx639 pushed a commit to Nachx639/clawdbot that referenced this pull request Jun 17, 2026

fix(cache): sort MCP tools deterministically to stabilize prompt cache (

e0e2609

openclaw#58037) Co-authored-by: George Zhang <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(cache): sort MCP tools deterministically to stabilize prompt cache#58037

fix(cache): sort MCP tools deterministically to stabilize prompt cache#58037
odysseus0 merged 1 commit into
openclaw:mainfrom
bcherny:cache/mcp-tools-sort

bcherny commented Mar 31, 2026

Uh oh!

greptile-apps Bot commented Mar 31, 2026

Uh oh!

This comment was marked as spam.

Uh oh!

odysseus0 commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

bcherny commented Mar 31, 2026

Problem

Fix

Verification

Follow-up (not in this PR)

Uh oh!

greptile-apps Bot commented Mar 31, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

This comment was marked as spam.

Uh oh!

odysseus0 commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants