Defining Agent Tools on Databricks: Retrieval, Unity Catalog Functions and the Tool-Calling Loop

1.Matching each knowledge source to a tool

Ordering tools well depends on defining them well, and the first choice is which kind of tool fits each data source. Databricks gives a recommendation for each case.

For questions about data in Unity Catalog tables, Databricks recommends Genie Agents. A Genie Agent holds up to 25 Unity Catalog tables that Genie can keep in context and query in natural language, and your agent reaches it through a managed MCP URL. When the agent should run AI-generated SQL through a SQL warehouse, use the managed Databricks SQL MCP server rather than building a custom tool. When the query is known ahead of time and only the parameters change, use a Unity Catalog SQL function. For unstructured documents, the managed AI Search MCP server gives the agent access to an AI Search index (formerly Vector Search).

Unity Catalog functions can also take actions, running custom logic that goes beyond language generation. Outside the structured-retrieval case, though, Databricks recommends MCP servers or logic defined directly in agent code, for faster execution and per-user authentication.

Sources123

2.Descriptions are how the LLM decides order

A tool's description is the LLM's only guide to when to call it. A Python callable registered with create_python_function must meet several rules. It needs type hints on every argument and on the return value. It cannot use *args or **kwargs. Its docstring must follow Google syntax, because the toolkit parses the docstring to tell the LLM how and when to use the function. Any libraries must be imported inside the function body.

In a multi-stage agent, the description can also say how a tool's output feeds the next step. In the SQL function below, the COMMENT tells the LLM that the returned customer ID can be used in other queries. That gives the LLM a reason to call this lookup first and pass its result into later tools.

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name_input STRING COMMENT 'Name of the customer whose info to look up'
)
RETURNS STRING
COMMENT 'Returns metadata about a particular customer, given the customer''s name, including the customer''s email and ID. The
customer ID can be used for other queries.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

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."
)

Sources3

3.The tool-calling loop that sequences the calls

Once tools are defined, they are bound to the LLM and run inside a loop. In the Databricks volume example, the user asks the agent to list the files in a volume, then read one and summarise it. The agent has two tools, list_volume_files and read_volume_file. Neither the code nor the developer fixes their order. On each pass the LLM returns tool calls, the loop runs them and adds the results to the message history as tool messages, and the LLM is called again. The loop ends when the LLM responds without requesting a tool, or when the iteration cap is reached.

for _ in range(5):  # max iterations
    response = llm_with_tools.invoke(messages)
    messages.append(response)
    if not response.tool_calls:
        break
    for tc in response.tool_calls:
        result = tool_map[tc["name"]].invoke(tc["args"])
        messages.append(ToolMessage(content=result, tool_call_id=tc["id"]))

Action tools carry a risk that retrieval tools do not. Databricks warns that executing arbitrary code in an agent tool can expose sensitive or private information the agent has access to. You are responsible for running only trusted code and for setting guardrails and permissions. When an agent runs in Databricks Apps, it gets access to a Unity Catalog function through an explicit EXECUTE grant on that function.

Sources32

Exam traps

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

1. 1.Unity Catalog functions are the recommended way to build every agent tool on Databricks.Why is that wrong?

   Databricks recommends UC functions specifically for structured retrieval with a known query. For most other cases it recommends MCP servers or logic written in agent code.

   Covered in Matching each knowledge source to a tool

2. 2.Calling Genie through its managed MCP server automatically passes the earlier conversation to Genie.Why is that wrong?

   The Genie MCP server invokes Genie as a tool, so no history is passed. To pass conversation context deterministically, call Genie as an agent in a multi-agent system.

   Covered in Matching each knowledge source to a tool