[FEATURE] Add consistent `description` fields to tool use (parity with Bash)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

The Bash tool has a description parameter that Claude fills on every call:

{
  "command": "git status --short",
  "description": "Show working tree status"
}

No other built-in tool has this field. PreToolUse hooks receive tool_name + tool_input but have no way to know why Claude is invoking the tool. For Bash, description bridges this gap. For Grep, Glob, Read, Edit, and Write, hooks must reverse-engineer intent from bare parameters.

Example

A hook sees Grep(pattern="validate_schema", path="/project"). Is Claude:

• Finding a function definition?
• Checking usage in a file it already found?
• Searching for a config key in YAML?

The pattern string is identical in all three cases. A description field would resolve the ambiguity the same way it does for Bash.

Why This Matters for Hooks

With updatedInput support (shipped in v2.0.10, #4368), hooks can now modify tool calls. But they still lack the context to know when to modify. The description field closes this gap — it lets hooks make intelligent routing, validation, and policy decisions based on (a notion of) intent rather than heuristics. Additionally, this would also provide an intent audit trail for AI tool use by organizations that want to better understand these details in enterprise-wide deployments.

Proposed Solution

Proposal

Add an optional description field to Grep, Glob, Read, Edit, and Write, using the same schema pattern Bash already uses. In exploring the session content, Claude already fills Bash descriptions with 100% compliance — extending the pattern to other tools should work identically.

Alternative Solutions

This is the best path we've found to directly catalog and understand Claude's intent for built-in tooling operations.

Priority

Critical - Blocking my work

Feature Category

API and model interactions

Use Case Example

_No response_

Additional Context

Related

• #4368 — PreToolUse hooks can modify inputs, but lack context for when to do so
• #19649 — Claude falls back to Bash grep partly because the Grep tool schema is underspecified
• #18594 — PostToolUse hooks want to modify output but need intent context