> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

<Note>
  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.
</Note>

### 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

```mermaid theme={null}
flowchart TD
    A[User Query + Parameters] --> B[Parameter Validation]
    B --> C[Build Filtered Query]
    C --> D[Vector Search<br>+ Metadata Filter]
    D --> E[Rerank Results<br>if enabled]
    E --> F[Format Response]
```

### 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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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

    ***
  </Accordion>
</AccordionGroup>

## API Reference

See [Public API v1 Reference](../api/public-api-v1) for tool management endpoints.

***

## Related Documentation

* [Tools Description Guide](../guides/tools-description) - Best practices for tool descriptions
* [Tools Overview](../features/tools) - Tool configuration
* [Knowledge Source Management](../features/knowledge-source-management) - Knowledge setup
* [AI Debugger](../features/ai-debugger) - Debug search results