Tool Retrieval

The problem, from first principles

An agent with hundreds of tools cannot put every description in the prompt: it would burn the context window and confuse the model. The scalable approach is tool retrieval: embed the user's request and each tool's description, rank the tools by similarity and show the model only the top few. Even without a neural embedding, classic TF-IDF gives a strong baseline. Words that appear in few tool descriptions ("invoice", "weather") carry more weight than words that appear in all of them ("get", "data"), and the cosine similarity between the weighted query and description vectors ranks the tools.

From theory to code

Implement rank_tools.

Constraints

• tools maps tool names to description strings. Tokenize with re.findall(r'[a-z0-9]+', text.lower()).
• Inverse document frequency over the descriptions only: idf(w) = log((N + 1) / (df(w) + 1)) + 1 where N is the number of tools and df(w) the number of descriptions containing w. Words absent from every description still get df = 0.
• The vector for a text is its term counts multiplied by idf. Score each tool by the cosine similarity between the query vector and the description vector (0.0 if either has zero norm).
• Return the names of the top_k highest scoring tools, sorted by score descending and then by name ascending.

Hints