[DOCS] Hooks docs omit `type: "mcp_tool"` hook handler

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Hook handler fields in the Hooks reference, plus the hook type overview in Automate workflows with hooks

Current Documentation

The hooks reference currently says:

Each object in the inner hooks array is a hook handler: the shell command, HTTP endpoint, LLM prompt, or agent that runs when the matcher matches. There are four types: Command hooks (type: "command"): run a shell command. HTTP hooks (type: "http"): send the event's JSON input as an HTTP POST request to a URL. Prompt hooks (type: "prompt"): send a prompt to a Claude model for single-turn evaluation. Agent hooks (type: "agent"): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision.

| type | yes | "command", "http", "prompt", or "agent" |

The guide also says:

Each hook has a type that determines how it runs. Most hooks use "type": "command", which runs a shell command. Three other types are available: "type": "http": POST event data to a URL. "type": "prompt": single-turn LLM evaluation. * "type": "agent": multi-turn verification with tool access.

What's Wrong or Missing?

Changelog v2.1.118 says hooks can now invoke MCP tools directly via type: "mcp_tool", but the current hooks docs still describe only four hook handler types and never mention mcp_tool.

That makes the reference inaccurate and leaves the new feature effectively undiscoverable. The current docs also use the phrase "MCP tool hooks," but the documented content is only about matching existing MCP tool calls in tool events, not configuring a hook handler that directly invokes an MCP tool.

Suggested Improvement

Update the hooks reference and guide to add type: "mcp_tool" as a documented hook handler type.

At minimum, document:

• which hook events support mcp_tool
• the required and optional fields for this handler type
• how its execution/output behavior differs from command, http, prompt, and agent
• a minimal JSON example showing a hook invoking an MCP tool directly
• the distinction between matching MCP tool names like mcp__server__tool and using a hook handler with type: "mcp_tool"

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | Hook handler fields says there are only four types and the type field only allows command, http, prompt, or agent |
| https://code.claude.com/docs/en/hooks-guide | Hook type overview says only three alternatives to command are available |

Total scope: 2 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Hooks can now invoke MCP tools directly via \type: "mcp_tool"\``