Build context sets using Gemini CLI

This document describes how to use the Gemini CLI and the MCP toolbox to build agent context files. These files contain templates, facets, and value searches that provide context for generating SQL queries from natural language. You will also use the DB Context Enrichment extension.

To learn about context sets, see Context sets overview.

To build an agent context file, perform the following high-level steps:

  • Prepare your environment
  • Generate targeted templates
  • Generate targeted facets
  • Generate targeted value searches
  • Optional. Generate bulk templates

Before you begin

Complete the following prerequisites before creating an agent.

Enable required services

Enable the following services for your project:

Prepare a Cloud SQL instance

Required roles and permissions

Grant executesql permission to Cloud SQL instance

To grant the executesql permission to Cloud SQL instance and enable the Cloud SQL Data API, run the following command: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Replace the following:
  • PROJECT_ID: The ID of your Google Cloud project.
  • INSTANCE_ID: The ID of your Cloud SQL instance.
To perform steps in this tutorial, sign in to Google Cloud, and then authenticate to the database using IAM authentication.

Prepare the database for value searches

To use semantic and trigram value searches, you must configure your Cloud SQL for MySQL instance to support vector embeddings and n-gram indexing.

  1. To enable the Cloud SQL for MySQL instance to perform semantic value searches, you must enable the following flags.

    1. Enable cloudsql_vector flag.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Enable enable-google-ml-integration flag to allow the Cloud SQL for MySQL instance to integrate with Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Create a vector column to store city embeddings

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Generate and store vector embeddings for city names

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. To enable the Cloud SQL for MySQL instance to perform trigram value searches, perform the following steps.

    1. Enable ngram_token_size flag.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Create a FULLTEXT index for trigram matching on the airport name

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Prepare your environment

You can build context set files from any local development environment or IDE. To prepare the environment, perform the following steps:

  • Install Gemini CLI
  • Install the DB Context Enrichment extension
  • Setup database connection

Install Gemini CLI

To install Gemini CLI, see Get Started with Gemini CLI.

Install the DB Context Enrichment MCP extension

The DB Context Enrichment extension provides a guided, interactive workflow to generate structured NL2SQL context from your database schemas.

For more information about installing the DB Context Enrichment extension, see DB Context Enrichment extension.

To install the DB Context Enrichment extension, follow these steps:

  1. Install the MCP Toolbox Gemini CLI extension:

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

  2. (Optional) Update the DB Context Enrichment extension.

    To verify the installed version of the extension, run the following command:

    gemini extensions list

    Make sure that the version is 0.4.2 or higher. To update the DB Context Enrichment extension, run the following command:

      gemini extensions update mcp-db-context-enrichment

    To update the DB Context Enrichment extension or to replace the GEMINI_API_KEY, run the following command:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Replace GEMINI_API_KEY with your Gemini API key.

Set up the DB Connection

The extension requires the database connection for context generation for fetching schemas, and executing SQL statements. To enable the extension to interact with your database, you must configure authentication credentials and define your database sources and tools.

Configure Application Default Credentials

You must configure Application Default Credentials (ADC) to provide user credentials for two main components:

  • Toolbox MCP server: uses credentials to connect to your database, fetch schemas, and run SQL for validation.
  • DB Context Enrichment extension: uses credentials to authenticate and call the Gemini API.

Run the following commands in your terminal to authenticate:

gcloud auth application-default login

Configure the tools.yaml file

The extension requires a database connection for context generation, which is supported by the MCP Toolbox and defined within the tools.yaml configuration file.

The tools.yaml file specifies your database source and tools required to either fetch schemas or execute SQL. The extension comes with pre-installed Agent Skills to help you generate the configuration.

  1. Start Gemini CLI:

    gemini

  2. Verify the skills are active by typing in the Gemini CLI: 

    /skills

  3. Type a prompt such as help me setup the database connection. The skill guides you through creating the tools.yaml file in your current working directory.

  4. Run the following command in Gemini CLI to apply the tools.yaml configuration to the Toolbox MCP server.

    /mcp reload

For more information about manually configuring the tools.yaml file, see MCP Toolbox Configuration.

Generate Context

The extensions installed earlier empower Gemini CLI to help you author context in the form of a JSON file.

Generate targeted templates

If you want to add a specific query pair as a query template to the context set, then you can use the /generate_targeted_templates command. For more information about templates, see Context sets overview

To add a query template to the context set, perform the following steps:

  1. In the same directory, start Gemini CLI:

    gemini

  2. Complete the Gemini CLI Authentication Setup.

  3. Verify that the MCP toolbox and the database enrichment extension are ready to use:

    /mcp reload

  4. Run the /generate_targeted_templates command:

    /generate_targeted_templates

  5. Enter the natural language query that you want to add to the query template.

  6. Enter the corresponding SQL query to the query template.

  7. Review the generated query template. You can either save the query template as a context set file or append it to an existing context set file.

The context set file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context set file and the query template, see Context sets overview.

Generate targeted facets

If you want to add a specific query pair as a facet to the context set file, then you can use the /generate_targeted_facets command.

To add a facet to the context set file, perform the following steps:

  1. Run the /generate_targeted_facets command:

    /generate_targeted_facets

  2. Enter the natural language query that you want to add to the query template.

  3. Enter the corresponding SQL query to the query template.

  4. Review the generated facet. You can either save the facet to a context set file or append it to an existing context set file.

The context set file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context set file and facets, see Context sets overview

Generate value search queries

If you want to generate value searches that specify how the system should search for and match specific values within a concept type, then you can use the /generate_targeted_value_searches command.

Make sure that you complete the steps in Prepare the database for value searches.

To generate a value index, perform the following steps:

  1. Run the /generate_targeted_value_searches command:

    /generate_targeted_value_searches
  1. Enter mysql to select MySQL as the database engine. Select default to select MySQL 8.0.

  1. Enter the value search configuration as follows:

    Table name: TABLE_NAME
Column name: COLUMN_NAME
Concept type: CONCEPT_TYPE
Match function: MATCH_FUNCTION
Description: DESCRIPTION

    Replace the following:

    • TABLE_NAME: The table where the column associated with the concept type exists.
    • COLUMN_NAME: The column name associated with the concept type.
    • CONCEPT_TYPE: The concept type that you want to define—for example, City name.

    • MATCH_FUNCTION: The match function to use for value search. You can use one of the following functions:

      • EXACT_STRING_MATCH: For exact match of two string values. Best for unique IDs, codes, and primary keys.
      • TRIGRAM_STRING_MATCH: For fuzzy-matching that calculates normalized trigram distance. Best for user searches and name correction. To use TRIGRAM_STRING_MATCH, you must prepare your database to support n-gram indexing.
      • SEMANTIC_SIMILARITY_MATCH: For semantic search on string values. Best for cross-lingual and synonym searches. For list of supported models, see Supported Google models. To use SEMANTIC_SIMILARITY_MATCH, you must prepare your database to support vector embeddings.

    • DESCRIPTION: (Optional) The description of the value search query.

  2. Add additional value searches as required. If you skip adding additional value indexes, the template-based SQL generation moves to the next step.

  3. Review the generated value searches. You can either save the context set as a context set file or append it to an existing context set file.

The context set file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the value index, see Context sets overview

Optional: Generate bulk templates

If you want to auto-generate the context set file based on your database schema and data, then you can use the /generate_bulk_templates command.

To auto-generate bulk templates, perform the following steps:

  1. Run the /generate_bulk_templates command:

    /generate_bulk_templates

  2. Based on your database schema, the template-based SQL generation takes you through a series of questions related to verifying the database information and granting permissions to access the database schema.

  3. Review the generated query template. You can either approve the template or update a query pair that you want to revise.

  4. Enter the natural language query that you want to add to the query template.

  5. Enter the corresponding SQL query to the query template.

  6. Review the generated query template. You can either save the query template as a context set file or append it to an existing context file.

  7. After you approve the query template, you can either create a new template file or append the query pairs to an existing template file. The query template is saved as a JSON file in your local directory.

The context set file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context set file, see Context sets overview.

What's next