Prompt–Tool Surface Coherence

Short answer

Prompt–tool surface coherence means that the model-facing instructions for a turn or session accurately describe the tools the model is actually allowed to call at that boundary. It is a harness correctness property, not merely a token optimization.

A modern agent host often has several independently evolving surfaces:

1. a registry of tools the product knows about;
2. the subset actually declared to the model for this request;
3. system-prompt guidance and examples that name tools;
4. permission or policy rules that may deny tools even if the host knows them;
5. deferred tools that can be discovered or revealed later; and
6. observability such as a context inspector that tells operators what the model received.

If those surfaces drift, the harness can tell the model to prefer a tool that is not callable, hide guidance for a tool that is callable, or show operators a context view that does not match the actual request. Safety guidance creates a separate constraint: dangerous-action, permission and denial rules must not disappear merely because a tool is absent from the current declaration set.

Qwen Code PR #12145, merged on 18 September 2026 as 377a5753a73fb04977c629c835a9f8bbff42848b, is useful current implementation evidence. It changes Qwen’s base system prompt so selected tool-specific guidance and examples are assembled from the session’s declared tool set instead of only static tool-name constants and feature flags. Qwen’s latest published stable release remains v0.24.0, so this is post-v0.24.0 current-main behavior, not stable-release behavior and not a UHP, MCP, ACP or A2A wire change.

The coherence boundary

A useful decomposition is:

Surface	Question it answers	Why it must remain distinct
Product tool registry	What tools can this harness implementation potentially provide?	Availability in the product does not mean the model received the tool this turn.
Declared tool set	What callable schemas were actually sent to the model?	This is the model’s immediate executable surface.
Prompt/tool guidance	What does the model believe it should call, prefer or avoid?	Stale prose can contradict the declared schemas.
Authorization policy	What calls may execute if proposed?	Permission is not equivalent to prompt visibility or tool declaration.
Deferred/reveal state	What may become callable later?	A session-start prompt can become stale after dynamic discovery.
Context/diagnostics view	What does an operator think the model saw?	Diagnostics must report the same snapshot used by the request, not a later registry state.

The core invariant is simple:

Model-facing guidance about callable tools should be derived from, or checked against, the same effective tool surface that the model request uses.

That does not require every policy sentence to be conditional. In fact, some safety and authorization text should remain unconditional precisely because it constrains behavior beyond the currently declared tool list.

The Qwen failure mode

Before PR #12145, Qwen’s base prompt described the tool surface from static ToolNames constants and configuration flags, while the request declarations came from ToolRegistry.getFunctionDeclarations().

Those two sources can diverge when a deployment:

• limits the eager tool set with tools.eager;
• denies an entire tool through permissions policy; or
• keeps a tool deferred behind ToolSearch.

The result is a correctness defect rather than just verbose prompting. The prompt can say, for example, “use this dedicated tool instead of a shell equivalent,” while the tool schema is absent from the request. The model then discovers the contradiction only after a failed call or an additional discovery round trip.

This failure pattern generalizes beyond Qwen. Any harness that independently generates prompt instructions and tool declarations can drift when plugins, permissions, feature flags, model modes, provider limits, MCP configuration or dynamic tool loading change one surface without updating the other.

Qwen’s session-start snapshot design

PR #12145 takes a deliberately bounded approach rather than rebuilding the prompt on every tool mutation.

At startChat, after the tool registry is warm and budget preloading has settled, Qwen snapshots the declared tool names onto Config. The main-session prompt builder receives that resolved set through an optional options object. Callers without a session snapshot retain the prior output, and an all-declared snapshot is required to render byte-identically to the old/default path.

The snapshot is important for diagnostics. Qwen’s /context path reads the same prompt-tool snapshot rather than recomputing from the live registry. If ToolSearch reveals another tool later, the live registry and the original system prompt may legitimately differ; /context should report what the prompt actually contains rather than silently rewriting history from newer registry state.

That gives Qwen a session-start coherence guarantee, not a claim of perfect dynamic coherence for every later reveal.

What gets gated — and what deliberately does not

The merged change narrows conditional rendering to two tool-bound prompt areas:

• lines in ## Using Your Tools; and
• tool-call example blocks.

A line or example survives only when every tool it names is declared. This avoids partially retaining an instruction that still references an unavailable tool.

Several classes remain unconditional by design:

• security and dangerous-action guidance;
• permission/denial guidance;
• Core Mandates and general communication behavior;
• CodeModeOnly guidance, whose tools are reached through tools.<name> inside exec rather than ordinary declared functions; and
• documented residues such as some bare read_file prose plus the special ask_user_question policy case.

This separation matters. Tool visibility and execution authorization are different controls. Removing a schema from a request does not make safety policy unnecessary, and leaving safety text visible does not make a denied tool callable.

Correctness first, tokens second

The PR explicitly corrects an earlier overstatement of the token savings. Its final measurements show:

Declared set	Prompt reduction	Approx. tokens	Example blocks kept
Seven common file tools	1,104 characters	~276	7/7
read_file + run_shell_command	4,327–5,069 characters	~1,082–1,267	4/7
read_file only	5,753–6,538 characters	~1,438–1,634	3/7
Default/all declared	0	0	unchanged

The default session therefore gains no token saving from this change. The architectural value is that trimmed deployments stop receiving instructions for tools they do not have. Token reduction is a secondary benefit that appears only when the declared surface was already narrowed.

That distinction is useful when evaluating prompt optimization claims: first ask whether the change makes the effective control surface more truthful; only then count prompt bytes or tokens.

Dynamic reveals and prompt-cache trade-offs

Qwen intentionally does not regenerate the base system prompt after every mid-session ToolSearch reveal in this first step.

The reason is architectural: the system prefix participates in prompt caching. Rebuilding it whenever a deferred tool becomes resident would mutate the cached prefix repeatedly and couple prompt assembly to every registry mutation path. PR #12145 therefore freezes the prompt against the session-start declared snapshot and names per-reveal regeneration as follow-up work.

This leaves a documented boundary:

session start
  registry warm/preload
      ↓
  declared-tool snapshot ─────► system prompt
      │                           │
      └──────────────────────────► /context view

later ToolSearch reveal
      ↓
  live declared tools change
      ↓
  original system prompt stays fixed in step 1

That is not the same as saying the prompt remains fully coherent with every later tool mutation. It is a controlled trade-off: session-start truth and cache stability are guaranteed; dynamic reveal coherence remains a separate problem.

Validation should test both directions

A safe gate must detect both under-gating and over-gating.

Qwen’s PR reports automated checks that:

• bracket the expected reduction for representative narrow tool sets;
• strip the gated sections and require everything else to remain identical;
• withhold each of 66 tool names across four example formats and assert that undeclared names do not survive in the gated text, with the documented ask_user_question exception;
• assert the inverse property that guidance for declared tools is retained;
• keep CodeModeOnly output identical with and without a snapshot;
• require the main prompt path to read the Config snapshot used by /context; and
• preserve the existing 17 full-prompt snapshots, plus byte identity for an all-declared snapshot.

The PR is also explicit about what that evidence does not prove: no live session was run by the author for the submitted evidence, no provider-side before/after request measurement was demonstrated, and there is no model-behavior eval showing that tool recall improved. The repository verification brief leaves those checks for follow-up.

This is the right evidence boundary to preserve on a reference site: static/CI invariants can prove prompt assembly properties, but they do not automatically prove better model behavior or lower end-to-end cost.

Relation to permissions and execution finality

Prompt–tool coherence should not be confused with the execution contract documented in Tool-call execution finality.

A host still needs to answer, separately:

• whether the tool call is authorized;
• whether approval is required;
• which execution owns the call;
• how cancellation propagates;
• whether the call actually settled; and
• what terminal evidence is trustworthy.

A perfectly coherent prompt can still invoke an unsafe or poorly finalized tool implementation. Conversely, a strong permission layer can block an unauthorized call even if stale prompt text mistakenly encouraged it.

The reusable layering is:

model-facing guidance
        ↓
declared callable schemas
        ↓
authorization / approval
        ↓
execution ownership + lifecycle
        ↓
terminal result / evidence

Each layer should consume the minimum truth it needs and should not silently substitute for another.

Relation to UHP, MCP and harness interoperability

This page describes harness-internal prompt and tool-surface integrity.

• UHP standardizes an external product/server/harness execution boundary. UHP 2026-09-12 does not require a particular system-prompt renderer or certify that an upstream harness’s internal prompt names exactly the tools its model request declares.
• MCP can supply tools to a host, but an MCP server being configured or connected does not prove every MCP tool is declared to the model on every turn. Host policy, discovery, filtering and provider limits can still narrow the effective model-facing set.
• ACP/A2A operate at different interoperability boundaries; Qwen PR #12145 does not revise either protocol.
• Harness adapters can add another place for drift if an adapter filters, renames or emulates tools while the upstream harness still generates guidance from its own assumptions.

For interoperability testing, this suggests an additional implementation question beyond wire conformance:

When the effective tool surface is narrowed by policy, adapter configuration or dynamic discovery, does the model-facing context remain truthful about what can actually be called?

That is an implementation-quality question today, not a new UHP conformance class.

See Qwen Code, Harness composition, Security and Lifecycle for the surrounding product, policy and execution boundaries.

Practical review checklist

When reviewing an agent harness, verify:

1. Single effective source: can you identify the exact tool set sent to the model request?
2. Prompt derivation: is tool-specific guidance generated or filtered from that effective set rather than a separate static catalogue?
3. Multi-tool instructions: if one instruction names several tools, is it removed when any required tool is absent?
4. Safety independence: do permission, denial and dangerous-action rules remain enforceable even when tool guidance is gated?
5. Dynamic discovery: what happens when a tool is revealed, installed or disabled after the system prompt was built?
6. Cache semantics: does refreshing tool guidance rewrite a cacheable system prefix, and is that trade-off intentional?
7. Diagnostics parity: does /context, debug output or telemetry show the prompt snapshot actually used by the request?
8. Inverse testing: do tests prove both that missing-tool guidance disappears and present-tool guidance remains?
9. Default regression: does the common all-tools path remain unchanged when no narrowing is configured?
10. Evidence boundary: are prompt-size measurements being mistaken for model-quality, latency or cost improvements without a live evaluation?

Primary sources

• Qwen Code PR #12145 — resident tool prompt assembly
• Qwen merge commit 377a5753
• Qwen design — Assembling the System Prompt from the Resident Tool Set
• Qwen verification brief
• Qwen issue #12032 — prompt/tool-surface mismatch
• Qwen Code v0.24.0