Anthropic advanced tool features - Tool Use, Tool Search and Programmatic Tool Calling

[otto-sellerstam]

Description

Would PydanticAI consider supporting Anthropic's recently announced advanced tool features as described in this article? These features include:

• Tool Search: defer tool loading (including context), then discover on-demand via search.
• PTC: tools execute within code sandbox, intermediate results don't pollute context.
• Tool Use Examples: few-shot examples alongside schema.

These seem particularly relevant for agents with large tool libraries (internal or MCP).

Generally I'm also curious about the sentiment on implementing vendor-specific functionality, especially on quite a fundamental level, as the above.

Happy to contribute a PR if there's interest.

References

No response

[chriestensonb]

I second this request. Both Tool Search and PCT would be very helpful for my use case.

[DouweM]

We intend to support all three of these features, and in fact a user already submitted a PR (#3550), that I asked to be split up into 3:

1. feat: Add ToolSearchTool and defer_loading for dynamic tool discovery #3620
   • Issue for supporting this for non-Anthropic models:
     • Support deferred loading of tools and discovery via tool search tool #3590
2. feat: Add Anthropic programmatically_callable (PTC) support #3627
   • Some notes on how to make this less Anthropic specific: feat: Add Anthropic advanced tool use features #3550 (comment)
   • Issues for supporting this for non-Anthropic models:
     • Light-weight code mode: Let model chain tool calls #3093
     • Code Mode: Tool Injection for mcp-run-python: Enable Python code to call back to agent tools with request/response flow #2037
3. Add examples field to ToolDefinition and send it to Anthropic #3619

I was out last week so I'm quite behind on PR review, but should get to these this week.

Generally I'm also curious about the sentiment on implementing vendor-specific functionality, especially on quite a fundamental level, as the above.

I left a few comments related to that on #3550:

• Programmatic Tool Calling (PTC): feat: Add Anthropic advanced tool use features #3550 (comment)
• Deferred Tool Loading / Tool Search (DTL/TS) feat: Add Anthropic advanced tool use features #3550 (comment)

The naive way to support these Anthropic features would be to add new fields on ToolDefinition that map to the Anthropic API fields, and then to document that these fields only work with Anthropic (or other providers that implement it in a compatible way in the future), while leaving users of other models/providers out of luck.

But since one of the main goals of Pydantic AI is to make switching between models seamless, and since both of these features can be implemented fully on the Pydantic AI side (see the issue links in the list above), the ideal solution would let the user opt-in to PTC and DTL/TS in a generic provider-agnostic way, that would then be handled either using framework code, or by leveraging the provider API's native functionality if available.

The implementation inside Pydantic AI would leverage toolsets:

• SearchableToolset (name TBD) would wrap a toolset (FunctionToolset, MCPServer, CombinedToolset, whatever you please) of searchable/deferred-loading tools, initially expose a single search_tools tool to the model. Then when that tool is used, the discovered tools would be included in the toolset's list of tool definitions that are sent to the model.
• ProgrammaticallyCallableToolset (name TBD) would wrap a toolset of code-callable tools and expose a single run_code tool to the model. This means that code-callable tools would not be available to the model as normal-callable tools, unless they are registered to the agent directly as well.

That will work for all models, but with Anthropic we can do better. Inside those toolsets get_tools methods, we can check ctx.model.profile.supports_deferred_loading (model profile field to be added), and if so, not just return the single search_tools tool + any discovered tools, but instead return all ToolDefinitions with defer_loading (new field) set to True. AnthropicModel can then detect that flag and pass it along to the API (with the beta header etc). PTC support would be analogous.

(Edit: Checking ctx.model.profile.supports_deferred_loading from inside SearchableToolset.get_tools is not going work right when the model is a FallbackModel, as we wouldn't be checking the underlying models' abilities. So similar to #3212, we likely need to arrange things such that the model classes themselves can determine how to handle the search tool and deferred-loading tools...)

Instead of requiring the user to create those toolsets manually, we could also add defer_loading and programmatically_callable fields to the @agent.tool decorator (and other places where tools can be registered), and then automatically detect that field to wrap those tools in the SearchableToolset or ProgrammaticallyCallableToolset. We'd then still get the behavior where if the model (i.e. Anthropic) natively supports them, those fields will be sent-through pretty much verbatim, whereas with other models we'd use the toolset.

I hope to be able to implement both those features in Pydantic AI this month, but we can start by shipping these fields with only Anthropic support, and then "back into" the all-model support in a subsequent release. We just need to make sure up front that we pick the right API that's generic enough to allow that, and don't accidentally expose Anthropic implementation details to all users.