›_ Claude Code Issues
Claude Code Issues / #54161

[DOCS] PostToolUse docs still describe MCP-only `updatedMCPToolOutput` instead of all-tool `updatedToolOutput`

Status Fixed / completed
Maintainer reply None cached
Activity 3 comments · opened Apr 28, 2026 · closed May 18, 2026

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

PostToolUse decision control, plus the Agent SDK hook output type/reference pages for PostToolUse hook responses.

Current Documentation

The docs currently say:

| updatedMCPToolOutput | For [MCP tools](#match-mcp-tools) only: replaces the tool's output with the provided value |

And the Agent SDK references still expose the old MCP-only field:

For PostToolUse hooks, you can set additionalContext to append information to the tool result.
``ts { hookEventName: "PostToolUse"; additionalContext?: string; updatedMCPToolOutput?: unknown; } ``

In the v2.1.121 changelog, Claude Code now says:

PostToolUse hooks can now replace tool output for all tools via hookSpecificOutput.updatedToolOutput (previously MCP-only)

What's Wrong or Missing?

The hooks reference and Agent SDK docs still document the pre-v2.1.121 behavior.

They describe PostToolUse output replacement as MCP-only and name the field updatedMCPToolOutput, but the changelog says this capability now works for all tools via hookSpecificOutput.updatedToolOutput.

That leaves the current docs contradictory in two ways:

A. The documented field name is outdated

Users looking up PostToolUse output replacement see updatedMCPToolOutput, not updatedToolOutput.

B. The documented scope is outdated

The reference says output replacement is only for MCP tools, but v2.1.121 expands it to all tools.

C. SDK type/reference pages still reflect the old behavior

The TypeScript and Python Agent SDK references still expose updatedMCPToolOutput and omit updatedToolOutput, so SDK users do not have accurate current guidance.

Suggested Improvement

Update the PostToolUse documentation to match v2.1.121:

  1. In https://code.claude.com/docs/en/hooks, replace the MCP-only updatedMCPToolOutput entry with updatedToolOutput, and state that it can replace tool output for all tools.
  2. Add a short PostToolUse JSON example that rewrites the output of a non-MCP tool so the new scope is explicit.
  3. Update the Agent SDK hook reference pages and the TypeScript/Python type docs to expose updatedToolOutput.
  4. If updatedMCPToolOutput is still accepted for backward compatibility, document that explicitly as a deprecated alias; otherwise remove it from the reference/types.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/hooks | 1274-1279 | PostToolUse decision-control table still documents updatedMCPToolOutput as MCP-only |
| https://code.claude.com/docs/en/agent-sdk/hooks | 236-239 | Agent SDK hook output overview says PostToolUse can append additionalContext, but does not mention output replacement for all tools |
| https://code.claude.com/docs/en/agent-sdk/typescript | 1376-1379 | PostToolUse type still exposes updatedMCPToolOutput?: unknown |
| https://code.claude.com/docs/en/agent-sdk/python | 2135-2138 | PostToolUseHookSpecificOutput still exposes updatedMCPToolOutput |
| https://platform.claude.com/docs/en/agent-sdk/hooks | 234-235 | Platform Agent SDK hook output overview has the same omission |
| https://platform.claude.com/docs/en/agent-sdk/typescript | 1238-1240 | Platform TypeScript SDK reference still exposes updatedMCPToolOutput?: unknown |
| https://platform.claude.com/docs/en/agent-sdk/python | 2076-2079 | Platform Python SDK reference still exposes updatedMCPToolOutput |

Total scope: 7 pages affected

Source: Changelog v2.1.121

Exact changelog entry: PostToolUse hooks can now replace tool output for all tools via hookSpecificOutput.updatedToolOutput (previously MCP-only)

View original on GitHub ↗

3 Comments

mohdashraf010897 · 5 months ago

A note before this docs change lands: empirically on 2.1.121, the docs are accidentally still correct for MCP. updatedToolOutput is silently dropped for MCP tools, while the legacy updatedMCPToolOutput is the only field that's honored.

Evidence in #54196 comment — counter-driven probe against mcp__adobe-wiki__search_wiki_content, four shapes tested for the new field (including the exact native tool_response shape) all dropped; legacy field with content-block-array shape works.

So updating the docs to point at updatedToolOutput for MCP looks like it should wait until the harness actually honors that field for MCP. The agent-sdk-typescript@0.2.121 changelog claim that "updatedMCPToolOutput is deprecated" is also premature for the same reason.

coygeek · 4 months ago

Issue #54161 Verification

Title: [DOCS] PostToolUse docs still describe MCP-only updatedMCPToolOutput instead of all-tool updatedToolOutput
Issue Date: 2026-04-28
Verification Date: 2026-05-18
Status: RESOLVED

---

Issue Summary

This issue reports that the PostToolUse documentation and Agent SDK references still described tool-output replacement as MCP-only via updatedMCPToolOutput, even though the changelog said the current field should be updatedToolOutput for all tools.

---

Verification Results

Claim 1: The main hooks reference should document updatedToolOutput for all tools instead of only MCP tools

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, lines 1477-1481, the PostToolUse decision control table now says decision can use updatedToolOutput, defines updatedToolOutput as replacing the tool output before Claude sees it, and keeps updatedMCPToolOutput only as an MCP-specific legacy field: "Prefer updatedToolOutput, which works for all tools".

Verdict: The primary Claude Code hooks reference now documents the all-tools field and no longer presents MCP-only replacement as the only current behavior.

---

Claim 2: The Agent SDK hooks overview should mention that PostToolUse can replace tool output, not just append additionalContext

Status: RESOLVED

At https://code.claude.com/docs/en/agent-sdk/hooks, lines 238-241, the Outputs section now says: "For PostToolUse hooks, you can set additionalContext to append information to the tool result, or updatedToolOutput to replace the tool's output entirely before Claude sees it."

At https://platform.claude.com/docs/en/agent-sdk/hooks, line 1381, the live page now says the same thing: PostToolUse hooks can use updatedToolOutput to replace the tool's output before Claude sees it.

Verdict: Both current SDK hooks overview pages now describe output replacement with updatedToolOutput rather than omitting it.

---

Claim 3: The TypeScript and Python Agent SDK references should expose updatedToolOutput instead of only updatedMCPToolOutput

Status: RESOLVED

At https://code.claude.com/docs/en/agent-sdk/typescript, lines 1537-1541, the PostToolUse output type now includes updatedToolOutput?: unknown; and marks updatedMCPToolOutput?: unknown; as deprecated: "Use updatedToolOutput, which works for all tools."

At https://code.claude.com/docs/en/agent-sdk/python, lines 2197-2201, PostToolUseHookSpecificOutput now includes updatedToolOutput: NotRequired[Any] and keeps updatedMCPToolOutput only as a deprecated alias.

At https://platform.claude.com/docs/en/agent-sdk/typescript, lines 2252-2256 on the current live page, the PostToolUse output type includes updatedToolOutput?: unknown; and marks updatedMCPToolOutput?: unknown; as deprecated.

At https://platform.claude.com/docs/en/agent-sdk/python, lines 2630-2634 on the current live page, PostToolUseHookSpecificOutput includes updatedToolOutput: NotRequired[Any] and keeps updatedMCPToolOutput only as a deprecated alias.

Verdict: The current live TypeScript and Python SDK references on both domains now expose updatedToolOutput and treat updatedMCPToolOutput as deprecated compatibility guidance rather than the only documented field.

---

Current State

| Claim | Status |
|-------|--------|
| Main hooks reference documents all-tool updatedToolOutput | RESOLVED |
| SDK hooks overview documents output replacement with updatedToolOutput | RESOLVED |
| TypeScript and Python SDK type references expose updatedToolOutput and deprecate updatedMCPToolOutput | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

  • URL: https://code.claude.com/docs/en/hooks
  • Lines 1477-1481: Documents updatedToolOutput for replacing tool output and says updatedMCPToolOutput is legacy for MCP tools, preferring updatedToolOutput for all tools.

---

Conclusion & Recommendation

Primary Concern: The issue reported that the public docs still presented PostToolUse output replacement as MCP-only and used the outdated field name updatedMCPToolOutput as the primary guidance.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current live docs now document updatedToolOutput in the primary hooks reference, explain it in the SDK hooks overview, and expose it in the TypeScript and Python SDK references on both documentation domains. The remaining mentions of updatedMCPToolOutput are now documented as deprecated compatibility aliases rather than current primary guidance.

---

github-actions[bot] · 3 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Same class of failure, ranked by community engagement — this issue is one of many, so it may not appear in the visible list: MCP server connection issues, Hooks & automation

Browse all Claude Code issue topics →