What causes "description is required for tool %q" in googleapis/mcp-toolbox?

Add a non-empty description field to the bigtablesql tool definition in tools.yaml

description is required for tool %q

Error message

description is required for tool %q

What it means

This error is thrown by the bigtablesql tool's Config.Initialize when the tool YAML/config has no description set. MCP Toolbox requires every tool to have a non-empty description because it is exposed to the LLM in the tool manifest. The tool fails to initialize and is not registered.

Source

Thrown at internal/tools/bigtable/bigtablesql/bigtablesql.go:70

	tools.ConfigBase   `yaml:",inline"`
	Type               string                 `yaml:"type" validate:"required"`
	Source             string                 `yaml:"source" validate:"required"`
	Statement          string                 `yaml:"statement" validate:"required"`
	Parameters         parameters.Parameters  `yaml:"parameters"`
	TemplateParameters parameters.Parameters  `yaml:"templateParameters"`
	Annotations        *tools.ToolAnnotations `yaml:"annotations,omitempty"`
}

// validate interface
var _ tools.ToolConfig = Config{}

func (cfg Config) ToolConfigType() string {
	return resourceType
}

func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
	if cfg.Description == "" {
		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
	}

	allParameters, paramManifest, err := parameters.ProcessParameters(cfg.TemplateParameters, cfg.Parameters)
	if err != nil {
		return nil, err
	}

	return Tool{
		BaseTool: tools.NewBaseTool(
			cfg,
			tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: paramManifest, AuthRequired: cfg.AuthRequired},
			allParameters,
		),
	}, nil
}

// validate interface

View on GitHub (pinned to 8cc6e09de2)

Solutions

Add a non-empty description field to the bigtablesql tool definition in tools.yaml
Verify the description is not empty after env-var/template expansion (e.g. ${TOOL_DESCRIPTION} resolving to "")
Check YAML indentation so the description key is nested under the correct tool
Run the server and inspect startup logs to confirm the tool now initializes

Example fix

// before (tools.yaml)
tools:
  execute-sql:
    kind: bigtable-sql
    source: my-bigtable-instance
// after
tools:
  execute-sql:
    kind: bigtable-sql
    source: my-bigtable-instance
    description: Executes SQL statements against BigQuery (Bigtable SQL layer).

Defensive patterns

Strategy: validation

Validate before calling

// Before loading the config / starting the server
cfg := bigtablesql.Config{Name: "execute-sql", Source: "my-bigtable-instance"}
if cfg.Description == "" {
    return fmt.Errorf("tool %q: description must be a non-empty string", cfg.Name)
}
// Or validate the parsed YAML:
// go-yaml: assert tools["execute-sql"].description exists and is non-empty

Type guard

func hasDescription(name, desc string) bool {
    return strings.TrimSpace(desc) != ""
}

Prevention

Always include a description field for every tool in tools.yaml
Add a CI lint step that parses tools.yaml and asserts description is non-empty for all tools
Avoid empty-valued environment placeholders like DESCRIPTION=${TOOL_DESC} without a default
Validate the toolbox config with the toolbox CLI before deploying

When it happens

Trigger: Calling Initialize on a bigtablesql Config whose Description field is the empty string — typically a tools.yaml entry of kind bigtable-sql that omits the description field or sets it to "".

Common situations: Hand-writing a tools.yaml and forgetting the description field; a templating/CI step stripping empty fields; copying a minimal example that omits description; YAML indentation errors that cause description to be parsed into a different key.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/3e363abc37ede27d. Report an issue: GitHub.