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