[DOCS] Docs Enhancement: SubagentStop hook for MCP tool observability

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents#scope-mcp-servers-to-a-subagent

Section/Topic

scope-mcp-servers-to-a-subagent

Current Documentation

Scope MCP servers to a subagent
Use the mcpServers field to give a subagent access to MCP servers that aren’t available in the main conversation. Inline servers defined here are connected when the subagent starts and disconnected when it finishes. String references share the parent session’s connection.
Each entry in the list is either an inline server definition or a string referencing an MCP server already configured in your session:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.
Inline definitions use the same schema as .mcp.json server entries (stdio, http, sse, ws), keyed by the server name.
To keep an MCP server out of the main conversation entirely and avoid its tool descriptions consuming context there, define it inline here rather than in .mcp.json. The subagent gets the tools; the parent conversation does not.

What's Wrong or Missing?

The mcpServers frontmatter documentation shows how to scope MCP servers to subagents, but doesn't mention how to monitor which tools are actually being called. Users have no documented way to track MCP usage without manual transcript inspection.

Suggested Improvement

Add a brief "Monitoring" subsection to the scoping docs:

Monitoring MCP Tool Usage

To track which MCP tools your subagents actually use, you can configure a SubagentStop hook.

See this example
for a practical hook that reports tool usage after each subagent completes.

Impact

Low - Minor confusion or inconvenience

Additional Context

Related: community requests for better agent observability (#5412, #5389). This pattern works with the existing SubagentStop hook—no new features needed.