Reading a Unity Catalog Tool's Contract: Names, Descriptions, Schemas

1.What an agent actually sees of a tool

In an exam scenario you get a task and a list of tools registered in Unity Catalog, each with a name, a description and parameters. That is also everything the agent's LLM gets. It can't read the function body. It decides from the contract the tool publishes.

On Databricks, these functions usually reach an agent through the Unity Catalog functions MCP server. This is a managed server that exposes the custom Python and SQL functions you register in Unity Catalog as tools the agent can call. Access is governed by Unity Catalog permissions. The server URL is scoped to a catalog and schema, /api/2.0/mcp/functions/{catalog}/{schema}. You can narrow it to a single function by adding the function name. The scope decides which candidate tools the agent can choose from at all.

The documentation answers this directly. Point a DatabricksMCPClient at the server URL and call list_tools(). It returns each tool's name, description and input schema at runtime, and the docs call this the reliable way to learn a server's exact tools and arguments. The same client works for managed, MCP Service and custom server URLs.

from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient(profile="DEFAULT")
host = workspace_client.config.host

# Use a managed, MCP Service, or custom server URL:
mcp_server_url = f"{host}/api/2.0/mcp/functions/system/ai"

mcp_client = DatabricksMCPClient(server_url=mcp_server_url, workspace_client=workspace_client)
tools = mcp_client.list_tools()
print(f"Available tools: {[t.name for t in tools]}")

Sources123

2.Where descriptions and schemas come from

Unity Catalog tools are Unity Catalog user-defined functions. Their contract is written at registration time, and the format depends on how the function was created.

If you register a Python callable with create_python_function, the toolkit reads the signature and the docstring. The signature must have type hints on every named argument and on the return value. Variable arguments such as *args and **kwargs are not allowed, and only types that SQL supports work. The docstring must follow Google style. The toolkit parses it to get the function description, the description of each argument, and the return value. So when an exam lists a tool's parameters with types and one-line explanations, that information usually comes from the Args: and Returns: blocks and the type hints.

def add_numbers(number_1: float, number_2: float) -> float:
  """
  A function that accepts two floating point numbers adds them,
  and returns the resulting sum as a float.

   ? :
    number_1 (float): The first of the two numbers to add.
    number_2 (float): The second of the two numbers to add.

  Returns:
    float: The sum of the two input numbers.
  """
  return number_1 + number_2

SQL functions carry the same information in COMMENT clauses. There is one comment on each parameter and one on the function. RETURNS declares the output type. The example below is the version the documentation describes as clear. The parameter comment says what value to pass, and the function comment says which fields come back.

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer whose info to look up.'
)
RETURNS STRING
COMMENT 'Returns metadata about a specific customer including their email and ID.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

Sources2

3.Reading a description the way a selector does

The documentation shows a second version of lookup_customer_info. It has the same body, but its comments are 'Name of the customer.' and 'Returns info about a customer.'. The docs say this version lacks important details, which makes it harder for agents to use the tool well. When you have to choose a tool, the useful question is what each description lets you work out about the task.

The difference matters when the task needs a specific output. Take the task "email the customer Acme Corp". The clear version promises an email address, so you can justify picking it by its output. The vague version may return exactly the same data, but its contract doesn't say so. Treat a vague description as weak evidence, and base your justification on what the contract actually states.

Sources2

4.How function names appear as tool names

A Unity Catalog function has a three-level name: catalog.schema.function. The Unity Catalog functions MCP server also exposes ready-made functions in the system.ai schema. One of them is the code interpreter, system.ai.python_exec, which lets an agent run Python code with no setup. Look at the name the documentation uses when it calls that same function as an MCP tool.

result = mcp_client.call_tool("system__ai__python_exec", {"code": "print('Hello, world!')"})
print(result.content)

In this call, the tool name is system__ai__python_exec, with double underscores where the dots were. The argument is a dictionary whose code key holds the Python source. Both details come from the input schema. This is why the documentation tells you to read the exact names and arguments from list_tools() rather than guess them from the catalog path. Also note that serverless compute must be enabled in the workspace to run the managed system.ai tools.

Sources13

Exam traps

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

1. 1.Two functions with the same body are interchangeable for selection, because the agent runs whatever the body does.Why is that wrong?

   The agent chooses from the description and parameter comments. A description that does not mention the field the task needs gives weaker grounds for choosing that tool, even if the body would return it.

   Covered in Reading a description the way a selector does

2. 2.The agent calls a Unity Catalog tool by its dotted path, for example system.ai.python_exec.Why is that wrong?

   The documented MCP call uses system__ai__python_exec. Read exact tool names and arguments from list_tools().

   Covered in How function names appear as tool names