Skip to Content

Search & Discovery

Intelligent tool discovery with semantic and hierarchical search.

Overview

ISA MCP provides two search strategies:

  1. Semantic Search - Vector similarity matching
  2. Hierarchical Search - Two-stage skill → tool routing

Both strategies can degrade to lexical mode when the semantic dependency is unavailable. In that case the server remains searchable, /health reports search.mode = lexical, and hierarchical search metadata records the fallback reason.

Find tools using natural language queries.

import aiohttp
 
async def search_tools(query: str, limit: int = 5):
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "http://localhost:8081/search",
            json={
                "query": query,
                "type": "tool",
                "limit": limit,
                "score_threshold": 0.3
            }
        ) as response:
            return await response.json()
 
results = await search_tools("weather information")
# Found 3 tools: get_weather, stream_weather, batch_weather

Search Parameters

ParameterTypeDefaultDescription
querystringrequiredSearch query
typestringalltool, prompt, resource
limitint10Maximum results
score_thresholdfloat0.3Minimum similarity

Two-stage skill-based routing for better relevance.

User Query: "schedule a meeting"
           │
           ▼
┌────────────────────────────────────────┐
│  Stage 1: Skill Matching               │
│  Result: calendar_management (0.92)    │
└────────────────────────────────────────┘
           │
           ▼
┌────────────────────────────────────────┐
│  Stage 2: Tool Search (Filtered)       │
│  Result: create_event (0.95)           │
└────────────────────────────────────────┘

Representative Skill Categories

The taxonomy is versioned and broader than the original six high-level buckets. Common examples include:

  • date-time
  • vector-semantic
  • text-search
  • web-search
  • http-api
  • task-management
  • calendar-events
  • analytics-metrics

Use GET /api/v1/search/skills?query=... to inspect the discoverable skill taxonomy directly.

Fallback Behavior

When no skills match, the system falls back to direct search across all tools. If the semantic dependency is unavailable entirely, the platform falls back to lexical search and reports that in the response metadata.

Search Metadata

{
  "query": "schedule meeting",
  "tools": [...],
  "metadata": {
    "strategy_used": "hierarchical",
    "skill_ids_used": ["calendar-events"],
    "stage1_skill_count": 1,
    "stage2_candidate_count": 12,
    "final_count": 5,
    "fallback_mode": null,
    "fallback_reason": null
  }
}

Example degraded fragment:

{
  "metadata": {
    "strategy_used": "hierarchical",
    "fallback_mode": "lexical",
    "fallback_reason": "ISA Model health check failed: ReadTimeout"
  }
}

Health and Fallback Reporting

Use /health to determine whether search is operating in semantic or lexical mode:

{
  "search": {
    "status": "ok",
    "mode": "semantic"
  }
}

or

{
  "search": {
    "status": "degraded",
    "mode": "lexical",
    "reason": "ISA Model health check failed: ReadTimeout"
  }
}

Performance

OperationTarget Latency
Semantic search< 100ms
Hierarchical search< 150ms
Schema loading< 50ms

Next Steps

Home