Parameterized Search Tool

Perform advanced, filtered searches with dynamic parameters

The AGO Parameterized Search Tool enables agents to perform advanced, filtered searches against the knowledge base with dynamic parameters.

Overview

Tool Name: ago_parameterized_search

This tool allows agents to execute targeted knowledge base searches with filters and parameters, enabling more precise document retrieval than standard semantic search.

Key Features

• Dynamic query parameters
• Filter by metadata fields
• Source-specific searches
• Date range filtering
• Tag-based filtering
• Structured result formatting

---

When to Use

Use parameterized search when:

Scenario	Example
Searching specific categories	”Find billing articles”
Date-constrained queries	”What changed last month?”
Source-specific searches	”Search only API docs”
Metadata filtering	”Articles tagged ‘enterprise‘“
Structured lookups	”Find product SKU-12345”

---

Configuration

Create Parameterized Search Tool

To create a parameterized search tool:

1. Navigate to AI Studio → Tools
2. Click Create Tool
3. Select Parameterized Search as the tool type
4. Configure the basic settings:
   • Name: Internal identifier (e.g., “product_search”)
   • Display Name: User-facing name (e.g., “Search Products”)
   • Description: What this tool does
   • Prompt: When the agent should use this tool
5. Configure search settings:
   • Sources: Select knowledge sources to search
   • Max Results: Maximum number of results to return
6. Define the Input Schema with filter parameters:
   • query (str): Search query text
   • category (enum): Filter by category
   • price_range (enum): Filter by price range
7. Click Save
8. Assign the tool to your agent

Configuration Fields

Field	Type	Description
sources	UUID[]	Knowledge sources to search
max_results	integer	Maximum results to return
score_threshold	float	Minimum relevance score (0-1)
include_metadata	boolean	Include document metadata

---

Input Schema

The parameterized search tool does not define a fixed input schema. Instead, filter parameters are configured dynamically when you create the tool via the Input Schema field. Define whatever parameters make sense for your search use case — the agent will populate them from the conversation.

Example Schema

A documentation search tool might define these input parameters:

Parameter	Type	Options	Description
query	str	-	What to search for
document_type	enum	guide, tutorial, reference, faq	Type of documentation
language	enum	en, fr, de, es (default: en)	Document language
include_archived	bool	true/false (default: false)	Include archived documents

All filter parameters are defined per-tool at configuration time. The agent passes them as tool arguments, and they are matched against document metadata during search.

UI Resource Rendering

You can optionally link a UI Resource template to the tool by setting the ui_resource_name field in the tool’s additional configuration. When set, search results are rendered using the linked template instead of plain text.

---

Search Behavior

Query Processing

Filter Types

Filter	Operator	Example
Exact match	=	category = "billing"
Contains	contains	tags contains "important"
Date range	>=, <=	date >= 2024-01-01
In list	in	status in ["active", "pending"]

---

Response Format

Standard Response

{
  "results": [
    {
      "document_id": "doc-uuid",
      "title": "Product Setup Guide",
      "content_snippet": "To set up your product, follow these steps...",
      "score": 0.92,
      "metadata": {
        "category": "guides",
        "last_updated": "2024-01-15",
        "tags": ["setup", "getting-started"]
      },
      "source": {
        "id": "source-uuid",
        "name": "Product Documentation"
      }
    }
  ],
  "total_count": 15,
  "query": "product setup",
  "filters_applied": {
    "category": "guides"
  }
}

---

Examples

Category-Based Search

Setting	Value
Name	support_article_search
Prompt	”Search support articles by category”
Input Parameters	query (str), category (enum: getting-started, troubleshooting, billing, integrations)

Date-Filtered Search

Setting	Value
Name	changelog_search
Prompt	”Search changelog and release notes”
Sources	Changelog knowledge source
Input Parameters	query (str), since (date), version (str)

Multi-Source Search

Setting	Value
Name	unified_search
Prompt	”Search across all documentation”
Input Parameters	query (str), sources (enum array: user-guide, api-docs, tutorials)

---

Best Practices

Query Design

• Focused queries: Keep search terms specific
• Meaningful filters: Only add filters that improve results
• Sensible defaults: Provide default values for optional parameters
• Clear descriptions: Help agents understand when to use each filter

Performance

• Limit results: Don’t retrieve more than needed
• Use source restrictions: Narrow search scope when possible
• Enable reranking: For better relevance on broad queries
• Cache common queries: For frequently asked questions

User Experience

• Explain filters: Tell users what filters were applied
• Show count: Indicate total available results
• Provide alternatives: Suggest broader search if no results

---

Troubleshooting

Issue: No results returned

Problem: Search returns empty results.

Solutions:

1. Check if filters are too restrictive
2. Verify source IDs are correct
3. Try broader query terms
4. Check if content exists in knowledge base

Issue: Irrelevant results

Problem: Results don’t match user intent.

Solutions:

1. Add more specific filters
2. Enable reranker
3. Improve query extraction in prompt
4. Adjust score threshold

Issue: Slow search performance

Problem: Searches take too long.

Solutions:

1. Reduce max_results
2. Restrict to specific sources
3. Simplify filter combinations
4. Check index health

---

API Reference

See Public API v1 Reference for tool management endpoints.

---

Related Documentation

• Tools Description Guide - Best practices for tool descriptions
• Tools Overview - Tool configuration
• Knowledge Source Management - Knowledge setup
• AI Debugger - Debug search results