How to Configure Tools
🔧 Tools · 📋 Prompt
The tools provider gives the agent callable tools — functions the LLM can invoke during the conversation loop. Each tool source contributes a set of related tools. You control which sources are active and how they behave.
List and Enable Tool Sources
za agents capabilities tool-sets list
za agents capabilities tool-sets configure <source-name>
Configure Provider Settings
za agents capabilities tool-sets settings
Tool Sources
| Source | CLI name | Description |
|---|---|---|
| Index Tools | index-tools | Search, browse, and inspect any Zeta Alpha index |
| Tag Tools | tag-tools | List, search within, create, and manage user tags |
| Document Tools | document-tools | Read, locate, and retrieve metadata for individual documents |
| User Document Tools | user-document-tools | Search and list the user's own uploaded documents |
| Web Tools | web-tools | Fetch and browse content from the web (optional extra web_tools) |
| Image Tools | image-tools | Validate images against retrieved document pages |
| DataFrame Tools | dataframe-tools | Load, analyze, and visualize tabular data (CSV/Excel) (optional extra dataframe_tools) |
| SQL Database Tools | sql-database-tools | Explore and query SQL databases (optional extra sql_tools) |
| Platform Docs | platform-docs | Browse and read Zeta Alpha platform documentation |
| Sub-Agent | sub-agent | Spawn isolated sub-agents for parallel work |
Index Tools
Search, browse, and inspect any Zeta Alpha index.
za agents capabilities tool-sets configure index-tools
Tools
| Tool | Description |
|---|---|
search | Search the knowledge base for documents matching a query, ranked by relevance |
browse | List documents by criteria with sorting — for exploring, not relevance-ranked |
get_filter_options | Discover available filter fields and their values for the current index |
get_document_fields | Discover metadata fields available on documents by inspecting a sample |
get_index_configuration | Retrieve index configuration: filters, sort options, sources, and indexes |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
fe_base_url | str | "https://search.zeta-alpha.com" | Frontend base URL for building source links |
page_size | int | 10 | Results per search page |
browse_page_size | int | 20 | Results per browse page |
default_retrieval_unit | "document" | "chunk" | "chunk" | Return precise passages or full documents |
default_retrieval_method | "knn" | "keyword" | "mixed" | "mixed" | Semantic search, keyword matching, or hybrid |
default_collapse_key | str or null | null | Group results by this field (deduplication) |
description | str | "" | Tell the agent what it's searching over |
description_field | str | "custom_metadata.metadata.abstract" | Field path for document descriptions |
metadata_fields | list[str] | ["...title", "...source", "...created"] | Metadata fields to extract from hits |
known_filters | list[FilterHint] | [] | Pre-defined filter hints (field_path, description, values, example_values) |
sort_field_mapping | dict[str, str] | {"date": "date", ...} | Map user-friendly sort names to backend field names |
Describe Your Knowledge Base
The most important settings for search quality are description and known_filters. Write description as you would describe the collection to a new researcher:
description (str) []: R&D papers from arXiv and top ML/AI conference venues (NeurIPS, ICML, ICLR), covering 2000–2026.
For known_filters, provide a JSON array:
known_filters (List[FilterHint]) [[]]: [{"field": "source", "description": "Publication venue"}, {"field": "year", "description": "Publication year"}]
Auto-Generate with the Index Explorer
Instead of writing the configuration by hand, use the Index Explorer — an instruction source that gives the agent a methodology to autonomously probe your document collection and generate a ready-to-use configuration.
Step 1: Enable the Index Explorer instruction source:
za agents capabilities instruction-sources configure index-explorer
Step 2: Start the development UI and tell the agent:
za agents dev
Run the Index Explorer
The agent will inspect the index structure, discover facets, run targeted searches, and output a complete configuration you can paste into your index-tools settings.
After the Index Explorer generates the configuration, you can disable it — it's only needed during setup.
Tag Tools
List, search within, create, and manage user tags (collections/folders of documents).
za agents capabilities tool-sets configure tag-tools
Tools
| Tool | Description |
|---|---|
list_user_tags | List all tags the user has access to (own or shared) |
list_documents_in_tag | List documents in a tag with pagination and metadata |
search_in_tag | Search for documents within a specific tag (semantic + keyword, scoped) |
tag_document | Add a document to a tag |
untag_document | Remove a document from a tag |
create_tag | Create a new personal tag with name and optional description |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
max_documents_per_page | int | 20 | Max documents per page when listing tag contents |
Document Tools
Read, locate, and retrieve metadata for individual documents by ID or fuzzy name.
za agents capabilities tool-sets configure document-tools
Tools
| Tool | Description |
|---|---|
read_document | Read the full content of a document by its document ID |
locate_document | Find a document by fuzzy title, URL, or file name |
retrieve_metadata | Get structured metadata for a list of documents by their IDs |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
page_size | int | 10 | Number of results for locate_document keyword search |
User Document Tools
Search and list the user's own uploaded documents.
za agents capabilities tool-sets configure user-document-tools
Tools
| Tool | Description |
|---|---|
search_my_documents | Search the user's private uploaded documents by content relevance |
list_my_documents | List the user's uploaded documents with pagination and metadata previews |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
list_page_size | int | 20 | Default page size for listing user documents |
Web Tools
Fetch and browse content from the web.
Install with pip install zetaalpha.agents[web_tools].
za agents capabilities tool-sets configure web-tools
Tools
| Tool | Description |
|---|---|
web_fetch | Fetch a web page and return its content as clean text/markdown |
web_search | Search the web using a federated search engine (only available if federated indexes exist) |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
output_markdown | bool | true | Return content as markdown instead of plain text |
max_content_chars | int or null | null | Truncate fetched content to this many characters |
timeout_seconds | float | 30.0 | Timeout for each fetch request |
cache_max_size | int | 50 | Maximum number of cached responses |
cache_ttl_seconds | float | 900.0 | Cache entry TTL in seconds |
upgrade_to_https | bool | true | Upgrade http:// URLs to https:// |
blocked_hostnames | list[str] or null | null | Additional hostnames to block from crawling |
Image Tools
Validate images against retrieved document pages using a multimodal LLM.
za agents capabilities tool-sets configure image-tools
Tools
| Tool | Description |
|---|---|
validate_image_hit | Visually compare a user-uploaded image against a rendered PDF page using a multimodal LLM |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
validation_prompt | str | (built-in Jinja template) | LLM prompt template for visual comparison |
render_dpi | int | 96 | DPI for rendering PDF pages to images |
DataFrame Tools
Load, analyze, and visualize tabular data from CSV/Excel files.
Install with pip install zetaalpha.agents[dataframe_tools].
za agents capabilities tool-sets configure dataframe-tools
Tools
| Tool | Description |
|---|---|
load_dataframe | Load a CSV/Excel document into a named DataFrame |
get_dataframe_schema | View column names, types, and sample values |
preview_dataframe | Preview the first few rows |
read_dataframe | Read rows with pagination |
count_dataframe_rows | Count total rows |
get_column_values | Get unique/top values of a specific column |
get_column_statistics | Get descriptive statistics for a numeric column |
get_missing_value_counts | Count missing/null values per column |
filter_dataframe_rows | Filter rows using conditions (eq, neq, gt, lt, in, contains, etc.) |
sort_dataframe_rows | Sort by a column |
aggregate_column | Sum, mean, min, max, count with optional group-by |
merge_dataframes | SQL-style join of two DataFrames |
concatenate_dataframes | Concatenate multiple DataFrames vertically |
create_basic_plot | Bar, line, or scatter charts |
create_multi_series_plot | Plots with multiple Y-series overlaid |
create_distribution_plot | Histogram or box plots |
create_time_series_plot | Time-series line plots with date parsing |
create_correlation_heatmap | Correlation heatmap for numeric columns |
No additional configuration beyond enabled.
SQL Database Tools
Explore schemas and query SQL databases — filter, sort, aggregate, join, and insert without writing raw SQL.
Install with pip install zetaalpha.agents[sql_tools]. For databases other than PostgreSQL, install the appropriate SQLAlchemy dialect driver.
za agents capabilities tool-sets configure sql-database-tools
Tools
| Tool | Description |
|---|---|
sql_list_tables | List accessible tables |
sql_get_table_schema | Get column names and types for a table |
sql_preview_data | Preview the first few rows of a table |
sql_read_data | Read rows with pagination |
sql_count_rows | Count total rows |
sql_get_row_by_pk | Get a single row by primary key |
sql_select_columns | Select specific columns (deferred plan) |
sql_get_column_values | Get distinct values of a column |
sql_filter_table_rows | Filter rows using conditions (deferred plan) |
sql_sort_table_rows | Sort rows (deferred plan) |
sql_aggregate_column | Sum, mean, min, max, count with optional group-by (deferred plan) |
sql_join_tables | Join two tables/plans on shared columns (deferred plan) |
sql_insert_row | Insert a single row |
Tools that produce intermediate results return a named reference for subsequent operations (e.g., filter → aggregate → sort → read).
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
connection_string | str | "" (required) | SQLAlchemy connection string |
allowed_schemas | list[str] or null | null (all) | Restrict access to these schemas |
allowed_tables | list[str] or null | null (all) | Restrict to these tables (schema.table) |
max_rows_per_query | int | 10000 | Maximum rows returned per read |
query_timeout_seconds | int | 30 | Query timeout in seconds |
Always use allowed_schemas and/or allowed_tables to restrict access. Use a read-only database user when the agent only needs to query.
Platform Documentation Tools
Browse and read the Zeta Alpha platform documentation, giving the agent self-knowledge about the platform.
za agents capabilities tool-sets configure platform-docs
Tools
| Tool | Description |
|---|---|
list_platform_doc_pages | List all available documentation pages from the sitemap |
read_platform_doc | Read a documentation page and return its content as text |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
docs_base_url | str | "https://docs.zeta-alpha.com" | Base URL of the documentation site |
sitemap_path | str | "/sitemap.xml" | Path to the sitemap XML |
max_content_chars | int or null | null | Truncate fetched page content |
cache_max_size | int | 50 | Maximum cached pages |
cache_ttl_seconds | float | 900.0 | Cache TTL for fetched pages |
sitemap_cache_ttl_seconds | float | 3600.0 | Cache TTL for the parsed sitemap |
timeout_seconds | float | 30.0 | HTTP request timeout |
Pair with the Platform Docs instruction source for a complete self-knowledge setup — instructions tell the agent what the platform can do, tools let it look up how.
Sub-Agent
Spawn isolated sub-agents to perform focused, parallel work.
za agents capabilities tool-sets configure sub-agent
Tools
| Tool | Description |
|---|---|
task | Launch an isolated sub-agent with a prompt and description for a focused unit of work |
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
verbose | bool | true | Include detailed behavioral guidance in tool description |
include_in_prompt | bool | true | Inject delegation instructions into the system prompt |
extra_instructions | str or null | null | Append additional delegation guidance |
tool_description | str or null | null | Fully replace the default tool description |
Sub-agents run in isolated context — they receive only the task prompt, not the parent conversation. Recursive delegation is blocked. Protected parameters (tenant, auth headers, index configuration) are carried through automatically.
The delegate tool (routing to named specialized agents) comes from the delegation provider, not the sub-agent tool source. See Configuring Delegation.