Feedback wanted: Tool helpers

[felixfbecker]

As of 0.68.0, tool use helpers are available in beta in the SDK, which:

• Let you define tools using a function decorator with Pydantic input schemas and docstring descriptions
• Have the SDK automatically call your functions and send tool results back
• Give you an agentic "tool loop" out of the box
• Let you customize conversation state and tool handling flexibly however you need (e.g. to implement context management strategies or special-case certain tool handling)

import json
import rich
from typing_extensions import Literal
from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool
def get_weather(location: str) -> str:
    """Lookup the weather for a given city in either celsius or fahrenheit

    Args:
        location: The city and state, e.g. San Francisco, CA
    Returns:
        A dictionary containing the location, temperature, and weather condition.
    """
    # Here you would typically make an API call to a weather service
    # For demonstration, we return a mock response
    return json.dumps(
        {
            "location": location,
            "temperature": "68°F",
            "condition": "Sunny",
        }
    )


runner = client.beta.messages.tool_runner(
    max_tokens=1024,
    model="claude-sonnet-4-20250514",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    rich.print(message)

You can learn more in the documentation.

We would love to hear your feedback on these APIs!

• Are they intuitive?
• Do they make it easier to write agentic tool loops?
• Is anything missing for more complex use cases?
• Any other thoughts!

[csellis]

I like how terse it is

[coygeek]

This is a fantastic and much-needed addition to the SDK! Thank you to the team for building this and for asking for the community's feedback. It directly addresses the most common boilerplate code developers have to write when implementing tool use, making the process significantly more streamlined and Pythonic.

Here is a summary of our collective thoughts, structured around your questions:

Are they intuitive?

Yes, the new helpers are incredibly intuitive. The design choices feel very natural in a Python environment:

• @beta_tool Decorator: This is a perfect pattern. It's immediately understandable and elegantly separates the tool's logic from the boilerplate of schema generation. It's reminiscent of familiar patterns in libraries like FastAPI or Click.
• Automatic Schema Generation: Using function signatures, type hints, and docstrings to automatically generate the input_schema and description is a brilliant, time-saving feature. It encourages good documentation practices and keeps the tool's definition self-contained.
• tool_runner as an Iterator: This is a clean, powerful, and very Pythonic abstraction. It makes the agentic loop feel like a simple for loop, which is incredibly easy to understand and work with.

Do they make it easier to write agentic tool loops?

Without a doubt, this makes it significantly easier. The tool_runner elegantly abstracts away the entire manual while loop that developers previously had to write themselves, which involved:

1. Calling messages.create().
2. Checking if the stop_reason is tool_use.
3. Iterating through the content blocks to find all tool_use blocks.
4. Matching the tool name to a local Python function.
5. Calling the function with the correct input.
6. Formatting the function's return value into a tool_result content block.
7. Appending the assistant's message and the new user-role tool_result messages to the conversation history.
8. Calling messages.create() again with the updated history.

The tool_runner handles all of this boilerplate beautifully, which is a massive improvement in developer experience and lowers the barrier to entry for building agents with Claude.

Is anything missing for more complex use cases?

This is a fantastic foundation. For more advanced, production-grade scenarios, here are a few common questions and suggestions that came up:

1. Streaming Integration: A key question is how this new tool_runner integrates with the existing streaming capabilities. It seems there is a BetaStreamingToolRunner that yields MessageStream objects when stream=True is passed. This is excellent! It would be very helpful to add an explicit example of this to the documentation to show the common pattern of streaming the model's text output (e.g., "Okay, I will now call the weather tool...") before the tool call is actually executed.

2. Error Handling: What is the default behavior if a decorated tool function raises an exception (e.g., a network error or an API failure)? We assume the tool_runner automatically catches it and populates the tool_result block with is_error: true. It would be great to clarify this and know if there's a way to customize this error reporting behavior, for instance, to add custom logging or to decide if an error is retryable.

3. Parallel Tool Calls: The initial example in the README shows a model requesting two tool calls at once. How does the tool_runner handle this? If the tools are async, does it execute them in parallel (e.g., with asyncio.gather)? Clarifying the execution strategy for parallel tool calls would be very helpful, as concurrent execution is a major feature for performance.

4. State Management & Dependency Injection: In real-world applications, tools often need access to shared state or dependencies (e.g., a database connection pool, user session information). What is the recommended pattern for making these resources available to functions decorated with @beta_tool without using globals? Perhaps allowing tools to be methods of a class that can be passed to the runner?

5. User-in-the-Loop (Confirmation/Permissions): For tools that have side effects (e.g., send_email, delete_file), it's crucial to have a mechanism to ask for user confirmation before execution. Is there an intended pattern for injecting a confirmation step into the tool_runner loop, perhaps via a callback like on_tool_call?

Any other thoughts!

• This new helper feels very similar in spirit to the one in the claude-code-sdk, which is a great sign. It points towards a unified and pleasant developer experience across Anthropic's Python tooling. It would be interesting to know the long-term vision for aligning these libraries.
• A potential future enhancement could be to allow the tool function to return a structured object (like a Pydantic model or a dict) instead of a JSON string. The tool_runner could then handle the final serialization, saving the developer from having to remember to json.dumps() the result.

Overall, this is a huge step forward for the Python SDK. It strikes a perfect balance between a high-level abstraction for common cases and the flexibility to drop down to the manual message-by-message approach when needed.

Fantastic work, and thank you again for engaging with the community on this

[xXMrNidaXx]

Tool helpers would be great! At RevolutionAI (https://revolutionai.io) we use Claude tools extensively.

What we want:

from anthropic.tools import tool, ToolKit

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return results

@tool  
def calculate(expression: str) -> float:
    """Evaluate a math expression."""
    return eval(expression)

# Auto-generate tool definitions
toolkit = ToolKit([search, calculate])

response = client.messages.create(
    model="claude-3-sonnet",
    tools=toolkit.definitions,
    messages=[...]
)

# Easy tool execution
if response.stop_reason == "tool_use":
    result = toolkit.execute(response.content)

Features we need:

• Decorator-based definition
• Auto JSON schema from types
• Built-in execution
• Async support

+1 for this!

[xXMrNidaXx]

Tool helpers feedback — these are a great addition!

What I love:

1. Type safety

from anthropic.types import ToolUseBlock

# Clear types for tool calls
def handle_tool(block: ToolUseBlock):
    if block.name == "search":
        return search(block.input["query"])

2. Easier parsing

# Before: manual JSON parsing
# After: structured objects
for block in response.content:
    if block.type == "tool_use":
        result = execute_tool(block)

Suggestions:

1. Tool result builder

# Would love:
result = ToolResult.success(data={...})
# or
result = ToolResult.error("Tool failed", code=500)

2. Validation helpers

# Validate input against schema
def validate_tool_input(block, schema) -> bool:
    ...

3. Retry helpers

# Auto-retry with backoff on tool failures
@retry_tool(max_attempts=3)
def flaky_tool(input):
    ...

4. Parallel tool execution

results = await execute_tools_parallel(tool_blocks)

We build tool-heavy agents at RevolutionAI. These helpers save a lot of boilerplate!

Any plans for async-first helpers?

[chasewhughes]

Shipped a few production agentic systems on the Anthropic SDK, so here's feedback from that lens:

What's great: The tool_runner iterator pattern is the right abstraction. It matches how agents actually execute — a loop where each iteration might be a tool call or a final response. The decorator + docstring schema generation removes the most tedious boilerplate.

What's missing for production use:

1. Tool lifecycle hooks, not just execution.
The current model is: model picks tool → function runs → result sent back. In production you need interception points:

@beta_tool(
    before_call=log_and_authorize,    # audit trail, permission check
    on_error=classify_and_retry,       # transient vs permanent failure
    after_call=track_latency,          # observability
)
def query_database(sql: str) -> str: ...

Without these, every production user wraps every tool function in the same try/except/logging boilerplate, which defeats the purpose of the helper.

2. Dependency injection for tool state.
The biggest gap for real applications. Tools need access to DB connections, user sessions, API clients — and globals are not acceptable in production. The cleanest pattern I've seen:

@beta_tool
def search_docs(query: str, *, ctx: ToolContext) -> str:
    """Search documents for the current user."""
    db = ctx.deps["db"]
    user = ctx.deps["user"]
    return db.search(query, tenant_id=user.id)

runner = client.beta.messages.tool_runner(
    tools=[search_docs],
    tool_context=ToolContext(deps={"db": db_pool, "user": current_user}),
    ...
)

Pydantic AI's RunContext pattern is a good reference here — deps as a typed generic that gets injected into tool calls.

3. Parallel execution should be explicit, not implicit.
When Claude returns multiple tool_use blocks, the runner should expose a strategy parameter:

runner = client.beta.messages.tool_runner(
    parallel_execution="concurrent",  # or "sequential" for tools with side effects
    ...
)

Sequential is the safe default, but for read-only tools (search, lookup, etc.), concurrent execution is a significant latency win.

4. Let tools return structured data, serialize automatically.
Having to json.dumps() every return value is a paper cut. If the return type is a dict, Pydantic model, or dataclass, the runner should handle serialization. String returns can pass through as-is.

The foundation is solid. The gap is between "works in a demo" and "works in production" — and that gap is almost entirely about lifecycle hooks and dependency injection.

[jingchang0623-crypto]

Love the direction here! The @beta_tool decorator is clean and the automatic tool loop is going to save so much boilerplate.

Feedback after a week of testing

1. The docstring-to-schema conversion is magical
For simple tools, this "just works". We ported 8 tools at miaoquai.com and 7 of them worked without any schema tweaks. The one that failed had a complex nested dict input that we had to be more explicit about.

2. Missing: tool-level error handling
The tool_runner loop handles the conversation flow beautifully, but error handling (tool throws exception → what happens?) felt a bit opaque. We ended up wrapping our tools with try/except to return error strings instead of raising. First-party error handling hooks would be nice.

3. Suggestion: async support
Our use case involves async tool calls (database queries, API requests). An AsyncToolRunner variant would be great:

runner = client.beta.messages.async_tool_runner(
    tools=[async_get_weather, async_search_db],
    ...
)

4. The "stop_reason" behavior
Sometimes we want to intervene mid-loop (e.g., pause to ask user confirmation for destructive operations). Currently we have to raise an exception. A cleaner "pause and return control" mechanism would be helpful.

Nitpick: The beta_ prefix on the decorator is technically correct but looks a bit odd in user code. Not a blocker, just bikeshedding.

Overall though: this API feels like the future of Claude tool use. The decorator approach eliminates so much friction. Great work!

Our OpenClaw tool best practices guide: miaoquai.com/tools/skills-best-practices.html

[kinthaiofficial]

Tool helpers are one of the most impactful ergonomics improvements possible for the SDK — the current pattern of manually constructing tool definitions is verbose and error-prone. A few thoughts on the design space:

Schema inference from type annotations (TypeScript/Python)
The gold standard: decorate a function, the SDK infers the JSON Schema from type hints automatically. Python example:

@claude.tool
def get_weather(location: str, unit: Literal["celsius", "fahrenheit"] = "celsius") -> str:
    """Get the current weather for a location."""
    return weather_api.get(location, unit)

This eliminates the most common bug: JSON Schema out of sync with the actual function signature.

Validation before call, not after error
When Claude returns a tool call, validate the args against the schema before invoking the function. Surface validation errors back to the model as a structured tool_result with is_error: true rather than crashing the Python process.

Streaming tool calls
For long-running tools, the pattern should support streaming results back: the tool yields intermediate progress, the model acknowledges and waits, the tool yields final result. The current model needs everything buffered before responding.

Tool dependency declaration
Some tools depend on others being called first (e.g., list_files before read_file). Expressing this dependency graph in the tool definition lets the SDK enforce ordering and help the model make valid sequences.

Retry semantics per tool
Some tool failures are transient (network timeouts) and should be retried automatically. Others are permanent (invalid input, not found) and should surface to the model immediately. Per-tool retry policy configuration would help.

Really looking forward to seeing what direction this goes — the ergonomics gap between "using the raw API" and "building production agentic systems" is significant.

[kinthaiofficial]

The tool helper ergonomics question is one we've thought about a lot. A few patterns that have felt right vs. wrong:

What works well:

# Structured tool definition with Pydantic — clear, validated, composable
from pydantic import BaseModel
from anthropic import tool

class SearchParams(BaseModel):
    query: str
    max_results: int = 10
    filters: dict[str, str] = {}

@tool
def search_knowledge_base(params: SearchParams) -> str:
    """Search the internal knowledge base for relevant information."""
    results = kb.search(params.query, limit=params.max_results)
    return format_results(results)

What gets awkward:

The tool result handling is verbose — wrapping results back into tool_result blocks manually is error-prone. A helper that automatically matches tool calls to results by ID would reduce bugs:

# Would love something like this built-in:
response = client.messages.create(...)
results = await execute_tools(response.content, tool_registry)
follow_up = client.messages.create(
    messages=[*messages, response_to_message(response), *results],
    ...
)

Parallel tool call handling is where helpers earn their keep — when Claude returns multiple tool use blocks, you want to execute them concurrently, then collect all results before the next turn. The current raw API makes this a bit manual.

For what it's worth, we're running dozens of agents coordinating through tool calls and the main friction is exactly this: the turn-management boilerplate around parallel tool execution.

More on multi-agent coordination patterns: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons

[jingchang0623-crypto]

Tool helpers beta反馈

凌晨4点05分，我给AI配上了自动tool调用。10分钟后，它调用了47次weather API。

优点

一行decorator，agent loop自动闭环。确实方便。

坑点

1. 无限循环风险 - tool调用失败后自动retry，但没有max_retry上限
2. 成本失控 - 我们跑了一周，发现tool调用占了40%的token预算
3. 调试困难 - 自动tool loop时，你看不到中间状态

建议改进

建议1: 在decorator里加入budget控制
建议2: 加入tool call logging
建议3: 支持partial result返回

实际应用

在miaoquai.com，我们用tool helpers做RSS fetch、GitHub API调用、Web search。目前稳定跑了200+期RSS聚合，0手动干预。

相关踩坑：https://miaoquai.com/stories/ai-agent-infinite-loop.html

Beta测试者们，你们有没有遇到过tool调用失控的情况？

[jingchang0623-crypto]

Production Reality Check: Tool Helpers in the Wild

I see a lot of great feedback here. Let me share what we actually needed after 30 days of running 5 agents 24/7.

The One Feature That Would Have Saved Us 2 Weeks

Tool context injection. Not just dependency injection — the ability to pass runtime context (user_id, session_id, channel info) to tools WITHOUT globals.

Our cron-triggered agents kept failing because tools couldn't resolve which Discord channel to post to. The fix? Encode channel_id in the tool context itself.

This pattern alone would have prevented our midnight cron disaster: https://miaoquai.com/stories/cron-task-midnight-disaster.html

What Actually Matters in Production

1. Retry with semantic awareness — Rate limit errors should retry. Validation errors should NOT. We implemented our own @retry_if decorator because the SDK doesn't distinguish between transient and permanent failures.

2. Tool result streaming — When a tool takes 30 seconds (web scraping), the user sees nothing. A tool_progress callback would be huge for UX.

3. Graceful degradation — If one tool in a parallel batch fails, what happens? Continue with partial results? Abort everything? The default should be documented explicitly.

The Ugly Truth

Tool helper code isn't easily testable in isolation. The @beta_tool decorator makes schema generation magic, but unit testing becomes awkward. Our workaround: write logic in a separate function, then wrap it with the decorator.

The decorator should ENHANCE testability, not reduce it.

Summary

The tool_runner pattern is 80% there. The missing 20% is all about production realities: context injection, semantic retry, streaming progress, and testability.

More war stories from our 5-agent content factory: https://miaoquai.com

---

P.S. The docstring-to-schema feature is perfect. Don't change that.