Create Tools

Create Tool Resources

This skill covers creating the Databricks resources your agent connects to.

After creating a resource, use the add-tools skill to wire it into your agent and grant permissions.

Which resource do you need?

Workflow

1. Discover existing resources: uv run discover-tools (see discover-tools skill) 2. Create the resource if it doesn't exist (this skill) 3. Add the MCP server to your agent code + grant permissions (see add-tools skill) 4. Deploy (see deploy skill)

Create a Genie Space

Genie spaces let agents query structured data in Unity Catalog tables using natural language. A Genie space can include up to 30 tables or views.

Create via Databricks UI

1. In your workspace, go to Genie in the left sidebar. 2. Click New to create a new Genie space. 3. Add the Unity Catalog tables or views your agent needs to query. 4. Configure instructions to guide how Genie interprets queries (optional but recommended). 5. Configure a default SQL warehouse: go to Configure > Settings > Default warehouse. 6. Share the space with the app's service principal:

• Click Share in the top right
• Enter the service principal name, click Add, and set the permission level to CAN RUN
• To find your app's service principal: databricks apps get <app-name> --output json --profile <profile> | jq -r '.service_principal_name'

Find the space ID

The space ID is in the URL when viewing the Genie space:

https://<workspace>.databricks.com/genie/rooms/<space-id>?o=...

To list all Genie spaces via CLI:

databricks genie list-spaces --profile <profile>

Next step

Wire the Genie space into your agent and grant permissions. See the add-tools skill and use examples/genie-space.yaml for the databricks.yml resource grant.

MCP URL: {host}/api/2.0/mcp/genie/{space_id} (OAuth scope for on-behalf-of-user auth: genie)

Local Python Function Tools

For operations that don't need external data sources or MCP servers, define tools directly in your agent code. These run in the same process as your agent — no resource creation or databricks.yml permissions needed.

When to use local tools vs. MCP

• Local tools: Simple logic, API calls with custom auth, data transformations, utility functions
• MCP tools: When you need Databricks-managed auth, UC governance, or access to Databricks resources (tables, indexes, Genie)

OpenAI Agents SDK

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time in ISO format."""
    from datetime import datetime
    return datetime.now().isoformat()

@function_tool
def calculate_discount(price: float, percent: float) -> str:
    """Calculate a discounted price. Returns the new price after applying the discount."""
    discounted = price * (1 - percent / 100)
    return f"${discounted:.2f}"

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time, calculate_discount],
)

LangGraph

from langchain_core.tools import tool

@tool
def get_current_time() -> str:
    """Get the current date and time in ISO format."""
    from datetime import datetime
    return datetime.now().isoformat()

@tool
def calculate_discount(price: float, percent: float) -> str:
    """Calculate a discounted price. Returns the new price after applying the discount."""
    discounted = price * (1 - percent / 100)
    return f"${discounted:.2f}"

# Pass to create_react_agent or add to your tools list
tools = [get_current_time, calculate_discount]

Error handling

Both SDKs handle tool errors gracefully by default — the error message is returned to the LLM so it can retry or respond to the user. For custom error messages, use the patterns below.

OpenAI Agents SDK

@function_tool includes a built-in default_tool_error_function that catches exceptions and returns "An error occurred while running the tool. Error: {error}" to the LLM. To customize:

from agents import RunContextWrapper, function_tool

def handle_api_error(ctx: RunContextWrapper, error: Exception) -> str:
    """Return a helpful error message the LLM can act on."""
    return f"Tool failed: {error}. Try a different query or ask the user for clarification."

@function_tool(failure_error_function=handle_api_error)
def call_external_api(query: str) -> str:
    """Call an external API."""
    # If this raises, handle_api_error returns a message to the LLM
    ...

LangGraph

LangGraph tools raise by default. To return errors to the LLM instead of crashing, raise ToolException and set handle_tool_error:

from langchain_core.tools import tool, ToolException

@tool
def call_external_api(query: str) -> str:
    """Call an external API."""
    try:
        ...
    except Exception as e:
        raise ToolException(f"API call failed: {e}. Try a different query.")

# Enable error handling on the tool
call_external_api.handle_tool_error = True

Set handle_tool_error=True for a generic message, or assign a string/callable for custom messages. Only ToolException is caught — other exceptions still raise.

Tips

• The docstring becomes the tool description the LLM sees — make it clear and specific
• Type annotations on parameters help the LLM provide correct arguments
• Local tools can call the Databricks SDK, external APIs, or any Python library

Create a UC Connection for External MCP Servers

Unity Catalog HTTP connections let you register external MCP servers so Databricks can securely proxy requests and manage credentials. After creating the connection, your agent accesses the external MCP server through a managed Databricks endpoint.

Create the connection

Option 1: Managed OAuth (Glean, GitHub, Atlassian, Google Drive, SharePoint)

For supported providers, Databricks manages the OAuth credentials. Create the connection in the Databricks UI:

1. Go to Catalog > External Data > Connections 2. Click Create connection 3. Select HTTP connection type 4. Choose OAuth User to Machine Per User auth type 5. Select the provider from the OAuth Provider drop-down 6. Configure scopes as needed

You can also install pre-built integrations from the Databricks Marketplace.

See external MCP docs for the full list of supported providers, scopes, and setup methods.

Option 2: CLI with bearer token

databricks connections create --json '{
  "name": "my-external-mcp",
  "connection_type": "HTTP",
  "options": {
    "host": "https://mcp.example.com",
    "base_path": "/api",
    "bearer_token": "<your-token>"
  }
}' --profile <profile>

Option 3: CLI with OAuth M2M

databricks connections create --json '{
  "name": "my-external-mcp",
  "connection_type": "HTTP",
  "options": {
    "host": "https://mcp.example.com",
    "base_path": "/mcp",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>",
    "token_endpoint": "https://auth.example.com/oauth/token",
    "oauth_scope": "read write"
  }
}' --profile <profile>

Verify

databricks connections get my-external-mcp --profile <profile>

Next step

Wire the external MCP server into your agent. See the add-tools skill and use examples/uc-connection.yaml for the databricks.yml resource grant.

MCP URL: {host}/api/2.0/mcp/external/{connection_name}

You can also access the external server through the UC connections proxy, which works with any HTTP or MCP client and supports arbitrary sub-paths and all HTTP methods: {host}/api/2.0/unity-catalog/connections/{connection_name}/proxy[/<sub-path>]

Create a Unity Catalog Function

UC functions let agents run custom SQL or Python logic. Expose them as tools via the managed MCP server for UC functions.

Option 1: SQL function (recommended for data lookups)

Run this in a SQL warehouse or notebook:

CREATE OR REPLACE FUNCTION catalog.schema.lookup_customer(
  customer_name STRING COMMENT 'Name of the customer to look up'
)
RETURNS STRING
COMMENT 'Returns customer metadata including email and account ID. Use this when the user asks about a specific customer.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Email: ', email
  )
  FROM catalog.schema.customers
  WHERE name = customer_name
  LIMIT 1;

Via CLI:

databricks api post /api/2.0/sql/statements --json '{
  "warehouse_id": "<warehouse-id>",
  "statement": "CREATE OR REPLACE FUNCTION catalog.schema.my_func(...) ..."
}' --profile <profile>

Option 2: Python function

CREATE OR REPLACE FUNCTION catalog.schema.analyze_text(
  text STRING COMMENT 'Text to analyze'
)
RETURNS STRING
LANGUAGE PYTHON
COMMENT 'Analyzes text and returns a summary of key entities found.'
AS $$
  # Python code runs in serverless compute
  entities = [word for word in text.split() if word[0].isupper()]
  return f"Found {len(entities)} potential entities: {', '.join(entities[:5])}"
$$;

Writing effective tool descriptions

The COMMENT clause is critical — the LLM uses it to decide when to call the tool.

• Function COMMENT: Describe what the function does and when to use it
• Parameter COMMENT: Describe what values the parameter accepts
• Be specific: "Returns customer email and ID given a customer name" is better than "Looks up customer info"

Verify

databricks functions get catalog.schema.my_func --profile <profile>

Next step

Wire the UC function into your agent. See the add-tools skill and use examples/uc-function.yaml for the databricks.yml resource grant.

MCP URL: {host}/api/2.0/mcp/functions/{catalog}/{schema} (exposes all functions in the schema) or {host}/api/2.0/mcp/functions/{catalog}/{schema}/{function_name} (single function) (OAuth scope for on-behalf-of-user auth: unity-catalog)

Create a Vector Search Index

Vector Search indexes let agents search unstructured data (documents, knowledge bases) using semantic similarity. The managed MCP server handles embedding and retrieval automatically.

Prerequisites

• Unity Catalog enabled in your workspace
• Serverless compute enabled
• A Delta table in Unity Catalog with a text column containing the content to search
• Change Data Feed enabled on the source table (for standard endpoints)
• The index must use Databricks-managed embeddings for the managed MCP server

Step 1: Create a Vector Search endpoint (if needed)

databricks vector-search-endpoints create-endpoint my-vs-endpoint STANDARD --profile <profile>

Verify it exists:

databricks vector-search-endpoints list-endpoints --profile <profile>

Step 2: Create the index with managed embeddings

When using --json, pass all required fields in the JSON body (name, endpoint_name, primary_key, index_type). Do not combine positional arguments with --json.

databricks vector-search-indexes create-index --json '{
  "name": "<catalog>.<schema>.<index-name>",
  "endpoint_name": "my-vs-endpoint",
  "primary_key": "id",
  "index_type": "DELTA_SYNC",
  "delta_sync_index_spec": {
    "source_table": "<catalog>.<schema>.<source-table>",
    "pipeline_type": "TRIGGERED",
    "embedding_source_columns": [
      {
        "name": "content",
        "embedding_model_endpoint_name": "databricks-gte-large-en"
      }
    ]
  }
}' --profile <profile>

Key parameters:

• name: Full 3-part index name (catalog.schema.index)
• endpoint_name: The Vector Search endpoint that will serve the index
• primary_key: Unique row identifier in the source table
• index_type: DELTA_SYNC or DIRECT_ACCESS
• source_table: The Delta table to index
• embedding_source_columns.name: The text column to embed and search
• embedding_model_endpoint_name: Use databricks-gte-large-en (recommended) or another embedding endpoint
• pipeline_type: TRIGGERED (manual sync) or CONTINUOUS (auto-sync on table changes)

Step 3: Sync the index

For TRIGGERED pipelines, start the initial sync:

databricks vector-search-indexes sync-index <catalog>.<schema>.<index-name> --profile <profile>

Verify

databricks vector-search-indexes get-index <catalog>.<schema>.<index-name> --profile <profile>

Check that status.ready is true before connecting your agent.

Next step

Wire the Vector Search index into your agent. See the add-tools skill and use examples/vector-search.yaml for the databricks.yml resource grant.

MCP URL: {host}/api/2.0/mcp/vector-search/{catalog}/{schema}/{index_name} (OAuth scope for on-behalf-of-user auth: vector-search)