Selecting Retrieval Tools and Tool Context for Custom Agents

1.Matching the tool to the task's data and query shape

A custom agent does not receive data directly. It receives tools, and each tool decides what slice of data the agent can reach. Scoping the agent's context therefore means picking tools that fit two things in the task: whether the data is structured or unstructured, and whether the query is known ahead of time or has to be generated. Databricks offers pre-configured MCP servers for immediate access to Genie Agents and SQL warehouses, as well as custom tools for specialised workflows.

For plain querying of Unity Catalog tables, Databricks recommends Genie Agents. The whole curated context from a Genie Agent comes along with that tool. Use the SQL MCP server when the agent itself writes the SQL. That server exposes SQL execution as a tool, and access is governed by Unity Catalog permissions. When the query is fixed and the agent only fills in values, a Unity Catalog SQL function is the narrowest scope available. Its COMMENT text describes to the agent what comes back, for example that the returned customer ID "can be used for other queries".

Sources1

2.Scoping what a retriever tool exposes

For unstructured content, the Databricks AI Bridge packages (databricks-langchain and databricks-openai) provide VectorSearchRetrieverTool, which queries a Databricks AI Search index. The tool's arguments are context decisions in their own right. They set how many documents return, which columns come with them, which filters narrow the search, and whether the query is ANN or HYBRID. The tool_name and tool_description are the only things the LLM reads when deciding whether to call the tool at all.

vs_tool = VectorSearchRetrieverTool(
  index_name="catalog.schema.index_name", # Index name in the format 'catalog.schema.index'
  num_results=5, # Max number of documents to return
  columns=["primary_key", "text_column"], # List of columns to include in the search
  filters={"text_column LIKE": "Databricks"}, # Filters to apply to the query
  query_type="ANN", # Query type ("ANN" or "HYBRID").
  tool_name="name of the tool", # Used by the LLM to understand the purpose of the tool
  tool_description="Purpose of the tool", # Used by the LLM to understand the purpose of the tool
  text_column="text_column", # Specify text column for embeddings. Required for direct-access index or delta-sync index with self-managed embeddings.
  embedding=embedding_model # The embedding model. Required for direct-access index or delta-sync index with self-managed embeddings.
)

Two settings depend on the index. With a direct-access index, or a Delta Sync index that uses self-managed embeddings, you must also specify text_column and an embedding model, as the last two arguments above do. Without them the tool cannot embed the query. The tool_description is required for every index type. A vague description leaves the agent guessing about when retrieval is relevant.

vs_tool = VectorSearchRetrieverTool(
  index_name="catalog.schema.my_databricks_docs_index",
  tool_name="databricks_docs_retriever",
   ? ="Retrieves information about Databricks products from official Databricks documentation."
)

Sources2

3.Conversation and access context across the tool boundary

Choosing a tool also determines which conversation context crosses into it. Through the MCP server, Genie sees each request without the turns that came before it. If a follow-up question such as "and for last quarter?" only makes sense with earlier turns, the calling agent must rewrite the question so it stands alone. Alternatively, use Genie as an agent in a multi-agent system (Public Preview), where you can pass in existing conversation context deterministically.

Access context works the same way. A Genie Agent must be shared with the users or service principals that call it. A Databricks App, for example, declares the Genie resource with CAN_RUN permission in databricks.yml. Inside Genie, the author's embedded warehouse credentials grant access to the warehouse only. Data access is still evaluated against each end user's own Unity Catalog permissions.

async with McpServer(
    url=f"{host}/api/2.0/mcp/ ? /<genie-space-id>",
    name="genie-space",
    workspace_client=workspace_client,
) as genie_server:

Sources13

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Connecting an agent to Genie through the managed MCP server lets Genie use the whole conversation to interpret follow-up questions.Why is that wrong?

   Through MCP, Genie is invoked as a tool and does not receive history. Calling Genie as an agent lets you pass conversation context deterministically.

   Covered in Conversation and access context across the tool boundary

2. 2.A VectorSearchRetrieverTool needs only an index name for any index type.Why is that wrong?

   Direct-access indexes, and Delta Sync indexes with self-managed embeddings, also require text_column and an embedding model.

   Covered in Scoping what a retriever tool exposes