Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] PostToolUse docs still describe MCP-only `updatedMCPToolOutput` instead of all-tool `updatedToolOutput` [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#54161•Fetched 2026-04-29 06:34:39
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeekmohdashraf010897mohdashraf010897
Timeline (top)
labeled ×4commented ×1cross-referenced ×1

Code Example

> {
>   hookEventName: "PostToolUse";
>   additionalContext?: string;
>   updatedMCPToolOutput?: unknown;
> }
>
RAW_BUFFERClick to expand / collapse

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 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.

{
  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:

PageLine(s)Context
https://code.claude.com/docs/en/hooks1274-1279PostToolUse decision-control table still documents updatedMCPToolOutput as MCP-only
https://code.claude.com/docs/en/agent-sdk/hooks236-239Agent 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/typescript1376-1379PostToolUse type still exposes updatedMCPToolOutput?: unknown
https://code.claude.com/docs/en/agent-sdk/python2135-2138PostToolUseHookSpecificOutput still exposes updatedMCPToolOutput
https://platform.claude.com/docs/en/agent-sdk/hooks234-235Platform Agent SDK hook output overview has the same omission
https://platform.claude.com/docs/en/agent-sdk/typescript1238-1240Platform TypeScript SDK reference still exposes updatedMCPToolOutput?: unknown
https://platform.claude.com/docs/en/agent-sdk/python2076-2079Platform 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)

extent analysis

TL;DR

Update the PostToolUse documentation to reflect the new behavior and field name introduced in v2.1.121, replacing updatedMCPToolOutput with updatedToolOutput for all tools.

Guidance

  • Review and update the documentation at https://code.claude.com/docs/en/hooks to replace updatedMCPToolOutput with updatedToolOutput and remove the MCP-only restriction.
  • Add a JSON example to demonstrate output replacement for a non-MCP tool.
  • Update the Agent SDK hook reference pages and TypeScript/Python type docs to expose updatedToolOutput and deprecate or remove updatedMCPToolOutput.
  • Verify the changes by checking the affected pages listed in the issue.

Example

{
  hookEventName: "PostToolUse";
  hookSpecificOutput: {
    updatedToolOutput: "New output value";
  }
}

Notes

The updates should be made to the specified pages, and the changes should be verified to ensure accuracy and consistency across the documentation.

Recommendation

Apply the suggested improvements to update the documentation and ensure it reflects the current behavior of PostToolUse hooks, allowing users to correctly utilize the feature for all tools.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#logging issue#authentication issue#prompt issue#agent setup#task chaining

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING