Complete Search Walkthrough

Step 1: Starting a search

Everything begins with a call to search_tools. Describe what you need in natural language — ToolPilot handles the intent parsing, semantic matching, and graph traversal behind the scenes.

{
  "query": "I need a fast key-value store for caching in a Node.js application"
}

The query gets routed through the 4-stage search pipeline: intent extraction, vector similarity search, graph expansion, and scoring. Depending on how specific your query is, you’ll either get results immediately or receive a clarification request.

Step 2: Receiving clarification

When ToolPilot needs more context to narrow down the best match, it responds with a clarification request instead of results. This is part of the Guided Discovery system — think of it as ToolPilot asking the right follow-up questions before making a recommendation.

{
  "type": "clarification",
  "query_id": "abc-123",
  "questions": [
    {
      "key": "deployment",
      "question": "Do you need a self-hosted solution or a managed cloud service?",
      "options": ["self-hosted", "managed"]
    },
    {
      "key": "language",
      "question": "What's the primary language of the project?",
      "options": ["TypeScript", "JavaScript", "Python", "Go"]
    }
  ]
}

Step 3: Responding to clarification

Send the answers back using search_tools_respond. Include the query_id from the clarification response so ToolPilot can continue the same search session.

{
  "query_id": "abc-123",
  "answers": {
    "deployment": "self-hosted",
    "language": "TypeScript"
  }
}

ToolPilot re-scores the candidate tools using your answers as additional filters. The graph traversal narrows down, and you get a refined set of results.

Step 4: Getting results

The response includes the top recommended tool along with alternatives. Each result carries a health score, category, and a summary pulled from the graph mesh.

{
  "type": "results",
  "recommended": {
    "name": "redis",
    "description": "In-memory data structure store, used as a database, cache, and message broker",
    "health_tier": "healthy",
    "health_score": 92,
    "category": "database",
    "tags": ["caching", "key-value", "in-memory"],
    "why": "Strong match for Node.js caching — excellent TypeScript client (ioredis), active maintenance, self-hosted"
  },
  "alternatives": [
    {
      "name": "memcached",
      "health_tier": "healthy",
      "health_score": 78,
      "why": "Simpler caching layer, but fewer data structures than Redis"
    },
    {
      "name": "keydb",
      "health_tier": "moderate",
      "health_score": 65,
      "why": "Multi-threaded Redis fork — good if you need higher throughput"
    }
  ]
}

Step 5: Evaluating the recommendation

Before committing to a tool, consider these factors:

• Health tier — Is the tool actively maintained? Check the score breakdown.
• Graph relationships — What other tools is it commonly paired with? Strong RELATED_TO edges suggest good ecosystem compatibility.
• Documentation quality — Does it have clear guides, API reference, and examples?
• Alternatives — Sometimes the second-best option is a better fit for your constraints.

Step 6: Reporting the outcome

After using the recommended tool, close the feedback loop by calling report_outcome. This is how ToolPilot learns — positive outcomes strengthen graph edges, and negative outcomes trigger decay so future searches surface better alternatives.

{
  "tool_name": "redis",
  "outcome": "success",
  "details": "Excellent caching performance for our use case"
}

Recap

The full search flow is: search_tools → (optional clarification via search_tools_respond) → evaluate results → report_outcome. Each interaction feeds back into the graph, making ToolPilot smarter over time. The more context you provide upfront, the fewer clarification rounds you’ll need.