Anthropic has made tool definitions dynamic: Claude API applications can now introduce or replace tools inside an ongoing conversation while preserving the prompt cache.
The change in one request flow
Claude API inline tools are available in beta through the inline-tools-2026-09-15 header. A mid-conversation system message can include a tool_addition block containing the full tool definition. The application can add a new tool, change a schema or move a server tool to a newer version without editing the original tools array.
Before this change, developers often had to declare every possible tool at the beginning or start a new cached prefix when the tool set changed. Inline definitions let an agent load capability when the workflow reaches the moment it is needed.
Why preserving the prompt cache matters
Long agent sessions can have large stable prefixes: system instructions, repository context, policies and earlier messages. Rewriting the initial tool array can invalidate that cache and force the provider to process the prefix again. Anthropic says inline tool changes avoid that invalidation.
| Change | Old operational cost | Inline-tool effect |
|---|---|---|
| Add a specialist tool | Rebuild the request prefix or declare it from the start | Insert the definition when required |
| Update a schema | Change the original tools array | Add the newer definition in conversation |
| Remove a tool | Restart or maintain application-side state | Remove it by reference |
| Load MCP capabilities | Fetch and translate definitions separately | Add an MCP toolset with the companion beta |
MCP tool-list pinning is the quieter important feature
When an application also sends the MCP connector beta header mcp-client-2026-09-15, an inline definition can describe an MCP toolset. Claude returns an mcp_tool_listing block recording the tools fetched from each server. Sending that block back pins the list for the continuing conversation.
Pinning reduces a subtle reproducibility problem. An MCP server can add, remove or change tools between turns. A recorded listing makes it clearer which capabilities the model saw at that moment. It does not verify that the server implementation behind a tool remained unchanged.
Dynamic capability also creates dynamic risk
A tool definition is part of the model’s operating environment. Adding one mid-session changes what actions are possible, which arguments the model can send and which service receives data. Applications should treat inline definitions like code or configuration changes, not harmless prompt text.
- Allow tools only from approved registries or servers.
- Record the definition hash, server identity and authorization scope.
- Validate schemas before they reach the model.
- Require fresh approval when a new tool increases the failure radius.
- Separate tool discovery from the credentials used to execute it.
- Pin listings for reproducible sessions, then deliberately refresh them.
A migration pattern for existing Claude agents
- Keep stable, frequently used tools in the initial tools array.
- Move rare or workflow-specific tools behind an explicit discovery step.
- Add one versioned inline definition only when the workflow needs it.
- Store the returned tool listing and audit metadata with the session.
- Test cache hits, latency and token cost before and after migration.
- Exercise schema changes, tool removal, authorization failure and MCP-server drift.
- Fall back to a new conversation when provenance cannot be established.
What inline tools do not solve
They do not make a tool safe, guarantee that Claude chooses it correctly or prevent a server from performing an unexpected action. They also do not replace application authorization. A model-visible schema may say a tool reads a ticket while the backend credential can edit an entire project. Enforcement has to happen at the service boundary.
Our WebMCP permission-boundary guide explains the same distinction for browser tools, while the cPanel MCP guide shows why server access and user authorization remain separate concerns.
The practical verdict
Inline tools make Claude agents more modular and can protect the economics of long cached conversations. MCP list pinning also improves reproducibility. The feature should be adopted with a tool-provenance ledger, versioned schemas and authorization controls, because dynamically adding capability is also dynamically expanding the attack and error surface.
A production team should record the tool-set version beside each agent run and replay a representative conversation whenever a definition changes. That turns a subtle mid-conversation capability shift into a reviewable release event. It also makes cost comparisons honest: measure the cache hit rate, input-token savings, tool-discovery latency and completed-task quality together instead of treating a lower token bill as proof that the workflow improved.
Primary sources
- Anthropic: Claude Platform release notes
- Anthropic: Mid-conversation system messages and tool changes
Checked September 23, 2026. Inline definitions and MCP tool-list pinning are beta Claude API features and may change.
