[DOCS] `TaskCreate` tool reference omits v2.1.169 input-repair and unloaded-tool schema-in-error changes

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

The "Tools reference" table row for TaskCreate (one-line description only) and the broader TaskCreate / Task tools documentation. The changelog for v2.1.169 (June 8, 2026) lists a behavior change for TaskCreate that is not surfaced anywhere in the user-facing docs.

Current Documentation

The TaskCreate row in the tools table at https://code.claude.com/docs/en/tools-reference currently reads:

| TaskCreate | Creates a new task in the task list | No |

The TaskCreate input shape is listed in the Agent SDK todo-tracking migration table:

| With TodoWrite | With Task tools | | Item shape: { content, status, activeForm } | TaskCreate input: { subject, description, activeForm?, metadata? }. TaskUpdate input: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status is "pending", "in_progress", or "completed"; set status: "deleted" to delete |

The TaskCreated hook section in https://code.claude.com/docs/en/hooks describes the hook but does not describe TaskCreate input validation behavior.

The MCP tool-search/deferral concept (the "unloaded tools" the changelog refers to) is documented in https://code.claude.com/docs/en/mcp:

Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context. From your perspective, MCP tools work exactly as before.

The v2.1.169 changelog entry is:

Improved TaskCreate reliability: malformed inputs are repaired automatically and validation errors for unloaded tools include the schema

What's Wrong or Missing?

A. The TaskCreate row does not document the v2.1.169 input-repair behavior

The changelog says "malformed inputs are repaired automatically", but neither the TaskCreate row in the tools table nor the Task tools migration table on todo-tracking mention that malformed TaskCreate calls are auto-repaired. Users encountering a task that was created with repaired/normalized values have no way to discover this behavior or learn which fields are normalized.

B. The "unloaded tools include the schema in validation errors" behavior is not documented

The changelog says validation errors for unloaded (deferred) tools now include the schema. The MCP tool-search docs describe the deferral concept, but no page documents that a validation error on a deferred tool's call now includes the tool's input_schema so the model (or a human reading the error) can correct the call without first loading the tool. The prior behavior (errors that don't name the expected shape) is also undocumented, so this improvement is invisible.

C. No dedicated Task tools reference exists

TaskCreate only appears as a one-line row in the tools table and as an input shape in the migration table. There is no per-tool reference section describing its accepted fields, the activeForm/metadata optionality, the auto-repair rules, or the new schema-in-error behavior. Other tools (Bash, Edit, Glob, Grep, Read, Write, Agent, etc.) all have dedicated "tool behavior" subsections; Task tools do not.

Suggested Improvement

Add a ## TaskCreate tool behavior subsection in tools-reference.md (matching the pattern of "Bash tool behavior", "Edit tool behavior", "Agent tool behavior", etc.) covering:

• Accepted input fields and their types: subject (string, required), description (string, optional), activeForm (string, optional, label shown while the task is in progress), metadata (object, optional, arbitrary key/value pairs passed through to the assigned TaskUpdate/TaskList results).
• The auto-repair behavior added in v2.1.169: malformed TaskCreate inputs (e.g. wrong types, missing required fields, extra unknown fields) are repaired automatically before the task is created. Note that repaired values are normalized silently and not surfaced in the tool result, so callers should still send well-formed input.
• The v2.1.169 schema-in-error behavior: when a tool call references a tool that is currently deferred (unloaded) by tool search, validation errors now include the tool's input_schema so the model can correct the call without first loading the tool definition. Note that this applies to deferred MCP tools in particular.
• A cross-reference to the TaskCreated hook event for users who want to enforce validation rules on the parent's side.
• A cross-reference to the Agent SDK todo-tracking guide for the migration path from TodoWrite.

Minimal alternative: at minimum, expand the TaskCreate row in the tools table to a short paragraph that names the auto-repair and unloaded-tool-schema behaviors and links to the related pages above.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 41 | TaskCreate row in the tools table (one-line description) |
| https://code.claude.com/docs/en/tools-reference | 49 | TodoWrite row mentions the Task tools but does not document TaskCreate behavior |
| https://code.claude.com/docs/en/changelog | 32 | Source changelog entry for the v2.1.169 behavior change |
| https://code.claude.com/docs/en/agent-sdk/todo-tracking | 203-208 | Task tools input/output shape table — does not mention auto-repair or schema-in-error |
| https://code.claude.com/docs/en/hooks | 1943-1984 | TaskCreated hook event — does not describe TaskCreate input validation behavior |
| https://code.claude.com/docs/en/mcp | 970 | Tool search/deferral concept (background for "unloaded tools") |
| https://code.claude.com/docs/en/agent-sdk/python | 2705-2707 | Python SDK TaskCreate tool entry — no behavior notes |
| https://code.claude.com/docs/en/agent-sdk/typescript | 1985-1987, 2512-2514 | TypeScript SDK TaskCreate tool entries — no behavior notes |

Total scope: 8 pages affected (1 primary + 7 cross-references).

Version context: Behavior applies to v2.1.169 (June 8, 2026) and later. The TaskCreate tool became the default in place of TodoWrite as of v2.1.142 (TypeScript Agent SDK 0.3.142, Python Agent SDK 0.3.142), so the change affects the default toolset for every Claude Code session.