Rename retreiver to tool

[samuelcolvin]

Feedback from numerous people including @intellectronica, @ricklamers, @bllchmbrs and @RamiAwar is that the word "retriever" is confusing, the universal feedback was

why is this not called a "tool"?

I can make the argument that while retrievers user tools, they're a sub-type of tool with a different semantic meaning until I'm blue in the face, but in the end:

1. I'd rather be descriptive than proscriptive, if most people thing of these things as tools, they're tools
2. While the primary use is to retrieve information, they can be used for actions too, and I don't see any reason why it's actually important that these decorated functions have no side effects.

So here I've renamed:

• @agent.retriever -> @agent.tool
• @agent.retriever_plain -> @agent.tool_plain

---

Open question:

there are some internal places where my wholesale renaming means a confusing number of things are now just called "tool".

Tools are used for two things (this hasn't changed)

1. @agent.tool - previously "retrievers", could also be called "optional tools" or "discretionary tools" since the LLM has the option to call them, or "retrieval tools"
2. structured return values (including each member of a union if a union of structured types is returned)

We probably need a better name than "tool" internally for (1) to differentiate, I've used retrieval_tool in Model.agent_model, any better suggestions? cc @dmontagu

Todo:

• decide on name of (1)
• fix docs which currently don't make much sense

[hyperlint-ai]

8 files reviewed, 2 total issue(s) found.

The style guide flagged several spelling errors that seemed like false positives. We skipped posting inline suggestions for the following words:

• [Tt]ool_plain
• [Vv]alidators
• [Dd]ocstring
• Pydantic
• [Aa]sync
• [Vv]alidator

[dmontagu]

It seems to me the only practical difference between a "retrieval" tool and a "structured return value" tool is that the structured return value tool is the actual response, whereas if the model calls a retrieval tool, it gets to continue generating responses, right? If that is right, I feel like it would make sense for the name reflect to this in Model.agent_model.

That said, I guess retrieval_tool is sensible even if the value it retrieves will always be None, because I guess that output will be the thing that feeds in as the next message in the list of messages right? So you can in some sense think of it as "retrieval", even if the value it is retrieving is not interesting.

I mean I was thinking return_tools and non_return_tools which I know sucks as a name but yeah, maybe retrieval_tools is fine.

[cloudflare-workers-and-pages]

Deploying pydantic-ai with    Cloudflare Pages

Latest commit:	eeec587
Status:	✅  Deploy successful!
Preview URL:	https://6f3952bb.pydantic-ai.pages.dev
Branch Preview URL:	https://tool-retriever.pydantic-ai.pages.dev

View logs

[samuelcolvin]

Done, in the end I went with "Function Tools" as a simple and understandable name, that didn't introduce any philosophy into what they would be used for, and clearly indicated the most obvious distinction between the two types of tools - those based on a function, and those that are not.