Retrieval Tools

Tools for searching and retrieving information from the knowledge base.

Available Tools

Tool	Description	Permission
`retrieval/search`	Semantic search across documents	`retrieval/search`
`retrieval/rerank`	Rerank search results	`retrieval/rerank`
`retrieval/search_and_rerank`	Combined search + rerank	`retrieval/search_and_rerank`

retrieval/search

Perform semantic search across indexed documents.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`limit`	integer	No	Max results (default: 10)
`collection`	string	No	Filter by collection
`filters`	object	No	Metadata filters
`min_score`	number	No	Minimum similarity score (0-1)
`include_content`	boolean	No	Include full chunk text

Example

python

from gateflow_mcp import MCPClient

client = MCPClient(agent_id="agent_abc123", api_key="gf-agent-...")

result = client.call_tool(
    name="retrieval/search",
    arguments={
        "query": "employee vacation policy",
        "limit": 5,
        "collection": "hr-documents",
        "include_content": True
    }
)

print(f"Found {len(result['results'])} results:")
for r in result["results"]:
    print(f"  - {r['title']} (score: {r['score']:.3f})")
    print(f"    {r['content'][:100]}...")

Response

json

{
  "results": [
    {
      "id": "chunk_abc123",
      "document_id": "doc_xyz789",
      "title": "Employee Handbook - Chapter 5",
      "content": "Vacation Policy\n\nAll full-time employees are entitled to...",
      "score": 0.95,
      "metadata": {
        "page": 23,
        "section": "Benefits"
      }
    },
    {
      "id": "chunk_def456",
      "document_id": "doc_xyz789",
      "title": "Employee Handbook - Chapter 5",
      "content": "Requesting time off requires submitting a request at least...",
      "score": 0.87,
      "metadata": {
        "page": 24,
        "section": "Benefits"
      }
    }
  ],
  "query": "employee vacation policy",
  "total_results": 2,
  "search_time_ms": 45
}

With Filters

python

result = client.call_tool(
    name="retrieval/search",
    arguments={
        "query": "contract termination clause",
        "collection": "legal-contracts",
        "filters": {
            "metadata.client": "acme-corp",
            "metadata.year": 2026,
            "classification": {"$in": ["internal", "confidential"]}
        },
        "min_score": 0.7
    }
)

retrieval/rerank

Rerank results using a cross-encoder model for improved relevance.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Original query
`documents`	array	Yes	Documents to rerank
`model`	string	No	Rerank model (default: `rerank-english-v3.0`)
`top_n`	integer	No	Return top N results

Example

python

# First, get search results
search_results = client.call_tool(
    name="retrieval/search",
    arguments={"query": "refund policy", "limit": 20}
)

# Then rerank for better relevance
reranked = client.call_tool(
    name="retrieval/rerank",
    arguments={
        "query": "refund policy",
        "documents": [r["content"] for r in search_results["results"]],
        "top_n": 5
    }
)

print("Top reranked results:")
for r in reranked["results"]:
    print(f"  Index {r['index']}: score {r['relevance_score']:.3f}")

Response

json

{
  "results": [
    {
      "index": 3,
      "relevance_score": 0.98,
      "document": "Our refund policy allows returns within 30 days..."
    },
    {
      "index": 0,
      "relevance_score": 0.92,
      "document": "To request a refund, please contact support..."
    },
    {
      "index": 7,
      "relevance_score": 0.85,
      "document": "Refunds are processed within 5-7 business days..."
    }
  ],
  "model": "rerank-english-v3.0",
  "processing_time_ms": 120
}

retrieval/search_and_rerank

Combined search and rerank in a single call for optimal results.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`limit`	integer	No	Final results to return (default: 5)
`initial_limit`	integer	No	Initial search results (default: 20)
`collection`	string	No	Filter by collection
`filters`	object	No	Metadata filters
`rerank_model`	string	No	Reranking model

Example

python

result = client.call_tool(
    name="retrieval/search_and_rerank",
    arguments={
        "query": "how to reset password",
        "limit": 5,
        "initial_limit": 20,
        "collection": "support-docs"
    }
)

print("Best matches:")
for r in result["results"]:
    print(f"  {r['title']}: {r['rerank_score']:.3f}")

Response

json

{
  "results": [
    {
      "id": "chunk_abc123",
      "document_id": "doc_support_001",
      "title": "Password Reset Guide",
      "content": "To reset your password, follow these steps...",
      "search_score": 0.88,
      "rerank_score": 0.97,
      "metadata": {
        "category": "account",
        "last_updated": "2026-01-15"
      }
    }
  ],
  "query": "how to reset password",
  "search_results": 20,
  "reranked_results": 5,
  "total_time_ms": 180
}

Search Strategies

Hybrid Search

Combine semantic and keyword search:

python

result = client.call_tool(
    name="retrieval/search",
    arguments={
        "query": "HIPAA compliance requirements",
        "search_type": "hybrid",
        "semantic_weight": 0.7,
        "keyword_weight": 0.3
    }
)

Multi-Query Search

Search with multiple query variations:

python

result = client.call_tool(
    name="retrieval/search",
    arguments={
        "queries": [
            "vacation policy",
            "time off rules",
            "PTO guidelines"
        ],
        "merge_strategy": "max_score",
        "limit": 10
    }
)

Filter Operators

Operator	Description	Example
`$eq`	Equals	`{"year": {"$eq": 2026}}`
`$ne`	Not equals	`{"status": {"$ne": "draft"}}`
`$gt`	Greater than	`{"pages": {"$gt": 10}}`
`$gte`	Greater or equal	`{"score": {"$gte": 0.8}}`
`$lt`	Less than	`{"size": {"$lt": 1000000}}`
`$lte`	Less or equal	`{"year": {"$lte": 2025}}`
`$in`	In array	`{"type": {"$in": ["pdf", "docx"]}}`
`$nin`	Not in array	`{"status": {"$nin": ["deleted"]}}`

Permissions

Grant retrieval access:

yaml

permissions:
  tools:
    - retrieval/search
    - retrieval/rerank
    - retrieval/search_and_rerank
  collections:
    - support-docs      # Can search these collections
    - product-docs
  data_classification:
    - public
    - internal         # Can access up to internal classification

Best Practices

Use reranking - For quality-critical applications
Set min_score - Filter out low-relevance results
Use collections - Scope searches appropriately
Apply filters - Narrow results with metadata
Tune limits - Balance quality vs latency

Next Steps

LLM Tools - AI model access
Document Tools - Process documents
Semantic Search - Search guide

Retrieval Tools ​

Available Tools ​

retrieval/search ​

Parameters ​

Example ​

Response ​

With Filters ​

retrieval/rerank ​

Parameters ​

Example ​

Response ​

retrieval/search_and_rerank ​

Parameters ​

Example ​

Response ​

Search Strategies ​

Hybrid Search ​

Multi-Query Search ​

Filter Operators ​

Permissions ​

Best Practices ​

Next Steps ​

Retrieval Tools

Available Tools

retrieval/search

Parameters

Example

Response

With Filters

retrieval/rerank

Parameters

Example

Response

retrieval/search_and_rerank

Parameters

Example

Response

Search Strategies

Hybrid Search

Multi-Query Search

Filter Operators

Permissions

Best Practices

Next Steps