import torch
import numpy as np
from typing import List, Dict, Any
from sentence_transformers import SentenceTransformer

class ToolQueryPlanner:
    """
    TOOLQP: Multi-step retrieval framework for AI agents
    Breaks complex queries into sub-queries for better tool matching
    """
    
    def __init__(self, tool_library: List[Dict], embedding_model: str = 'all-MiniLM-L6-v2'):
        self.tools = tool_library
        self.embedder = SentenceTransformer(embedding_model)
        self.tool_embeddings = self._embed_tools()
    
    def _embed_tools(self) -> np.ndarray:
        """Create embeddings for all available tools"""
        tool_descriptions = [tool['description'] for tool in self.tools]
        return self.embedder.encode(tool_descriptions)
    
    def decompose_query(self, query: str) -> List[str]:
        """Break complex query into sub-queries"""
        # Example decomposition logic - can be enhanced with LLM
        if 'plan' in query.lower() and 'dinner' in query.lower():
            return [
                "find romantic restaurant",
                "check availability for 2 people",
                "find nearby florist",
                "wine pairing recommendations",
                "transportation options"
            ]
        return [query]
    
    def retrieve_tools(self, query: str, top_k: int = 3) -> List[Dict]:
        """Multi-step retrieval using query decomposition"""
        sub_queries = self.decompose_query(query)
        selected_tools = []
        
        for sub_query in sub_queries:
            query_embedding = self.embedder.encode(sub_query)
            similarities = torch.nn.functional.cosine_similarity(
                torch.tensor(query_embedding).unsqueeze(0),
                torch.tensor(self.tool_embeddings)
            )
            top_indices = similarities.topk(top_k).indices
            
            for idx in top_indices:
                tool = self.tools[idx]
                if tool not in selected_tools:
                    selected_tools.append(tool)
        
        return selected_tools[:top_k]

# Usage example:
tool_library = [
    {"name": "restaurant_finder", "description": "Find restaurants by cuisine and location"},
    {"name": "calendar_check", "description": "Check availability and book appointments"},
    {"name": "florist_locator", "description": "Find nearby flower shops"},
    {"name": "wine_recommender", "description": "Suggest wine pairings for meals"},
    {"name": "transport_booking", "description": "Book taxis or rideshares"}
]

planner = ToolQueryPlanner(tool_library)
result = planner.retrieve_tools("Plan a sophisticated anniversary dinner")
print(f"Selected tools: {[t['name'] for t in result]}")

The Single-Shot Retrieval Bottleneck

Imagine asking a personal assistant to "plan a sophisticated anniversary dinner." A good assistant wouldn't just search for "restaurant" and pick the first result. They'd break it down: find a romantic venue, check availability, look up a florist, research wine pairings, and perhaps book transportation. This is the fundamental challenge facing today's most advanced LLM-based autonomous agents. They have access to thousands of digital "tools"—APIs, functions, and software capabilities—but their method for finding the right ones is often as crude as a single Google search for a multi-faceted problem.

This is the core issue addressed by new research introducing TOOLQP (Tool Query Planning). As tool libraries for agents grow into the thousands and become dynamic—constantly updated with new APIs and capabilities—the standard retrieval method, known as single-shot dense retrieval, is breaking down. It's creating a critical bottleneck in the quest for truly capable AI agents that can reliably execute complex, multi-step tasks.

Why Your AI Assistant Can't Assemble IKEA Furniture

The failures of current systems stem from two major disconnects. First, there's the abstraction gap. A user might ask an agent to "analyze market sentiment for our new product launch." This high-level goal needs to be translated into a sequence of technical operations: perhaps calling the Twitter API to scrape tweets, using a sentiment analysis model, querying a financial news database, and then compiling the results into a report. A single embedding vector from the user's query struggles to map to all these disparate, technical tool descriptions simultaneously.

Second, and more critically, is the composition problem. Fixed-size embedding vectors, the standard currency of retrieval, are terrible at modeling combinations. The tool sequence [A, B, C] is fundamentally different from [B, A, C] or just using tool A alone. A single vector search cannot capture the intent behind a specific orchestration of tools. It's like trying to find the recipe for Beef Wellington by searching for "beef" and "pastry"; you'll get thousands of results, but not the specific, ordered procedure you need.

"The assumption that a complex user need can be captured in one static query vector is flawed," the research argues. This leads to agents either retrieving irrelevant tools or, more often, missing the crucial specialized tool needed in a later step, causing the entire planned workflow to fail.

The High Cost of Retrieval Failure

These aren't academic concerns. In practical tests, the performance of single-shot retrievers plummets as tool libraries scale and tasks become more compositional. An agent trying to "book international travel and file an expense report" might successfully retrieve the flight booking API but completely miss the currency conversion tool needed to calculate the expense, or the specific internal reporting system required. The result is a half-executed task and a frustrated user. For enterprise applications—where agents are promised to automate business processes—this unreliability is a non-starter.

TOOLQP: Teaching Agents to Think Before They Search

The proposed TOOLQP framework offers a paradigm shift: model retrieval as iterative query planning. Instead of taking the user's query and firing it once at a massive tool database, the system first engages in a planning phase. It breaks the abstract goal down into a multi-step reasoning chain, and at each step, formulates a new, precise, and contextualized query to find the next tool.

Here’s how it works in practice. Faced with the task "analyze market sentiment," a TOOLQP-powered agent might:

• Step 1 (Plan): Reason that it needs social media data. It generates a new, specific query: "Search recent tweets containing keywords [ProductX, launch]."
• Step 2 (Retrieve & Plan): It retrieves a Twitter scraper API. With that in mind, it reasons the next step is analysis. It generates query: "Perform sentiment classification on a list of text documents."
• Step 3 (Retrieve & Plan): It retrieves a sentiment analysis model. Finally, it plans for output, querying: "Generate a summary report with key metrics and charts."

This lightweight planner, typically a small language model or a prompted LLM, sits on top of any existing dense retriever (like those using OpenAI's embeddings or open-source models). It doesn't replace the retriever; it makes it radically more effective by feeding it better, step-by-step questions.

The Compound Advantage of Stepwise Precision

The magic is in the compounding effect of precision. Each intermediate query is informed by the previous step's retrieval. Knowing you have a "Twitter scraper" tool allows the planner to ask for a tool that processes "Twitter JSON output," which is far more precise than asking for a generic "data processor." This contextual chaining dramatically narrows the search space at each turn, increasing the likelihood of finding the exact right tool for the specific job at that specific point in the workflow.

Early benchmarks cited in the research are promising. On compositional tool-use benchmarks, TOOLQP-style planning showed significant improvements in retrieval accuracy over single-shot baselines, particularly for tasks requiring 3 or more tools in sequence. The failure mode changes from "missing the tool" to "faulty planning," which is often easier to debug and correct.

The Road to Truly Capable Agent Ecosystems

The implications of solving tool retrieval are vast. First, it makes massive, open-ended tool libraries practical. Developers could expose hundreds of internal APIs to an agent, trusting it to find and combine them correctly, enabling automation of previously bespoke workflows. It moves us closer to the vision of a "software-defined employee" that can learn to use new tools as easily as reading their documentation.

Second, it enables dynamic and personalized tool sets. Tools could be added, deprecated, or updated in real-time. An agent's personal "toolbox" could be tailored to a user's specific software subscriptions (Salesforce, Google Workspace, QuickBooks) without needing hard-coded integrations. The planner simply learns what's available at retrieval time.

However, challenges remain. Query planning adds latency—multiple retrieval steps cost more than one. The research into TOOLQP focuses on making this planner "lightweight," but for real-time applications, this overhead must be minimized. Furthermore, the planner itself must be robust; a bad planning step can lead the entire process astray.

The Next Frontier: Learning from Retrieval Failures

The most exciting future direction lies in closing the loop. Today's retrieval is a one-way street: query → tools. The next generation of systems will likely treat retrieval as an interactive process. If a retrieved tool doesn't work as expected during execution, that feedback could be fed back to the planner to reformulate its query or adjust its strategy, creating a self-improving retrieval system. This turns a static tool library into a learnable environment for the agent.

A Stepwise Leap Forward

The pursuit of general-purpose AI agents has been fixated on reasoning and action. TOOLQP highlights that a humble, overlooked component—retrieval—may be the linchpin. By reframing the search for tools as a problem of stepwise query planning, it addresses the critical abstraction and composition gaps head-on.

This isn't just about making agents slightly better at using tools. It's about making the entire paradigm of tool-augmented agents scalable and reliable. As one researcher noted, "You can have the best reasoning engine in the world, but if it can't find the right wrench, it will never fix the pipe." Frameworks like TOOLQP are building a better toolbox—and, more importantly, a smarter way to look inside it.

The era of the single-shot AI query is ending. The future of agentic AI will be multi-step, iterative, and planned. The tools are out there. The key is teaching our AI how to ask for them, one step at a time.