googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for the bigquery-conversational-analytics tool validates that a description was provided before constructing the tool. An empty description is rejected because the tool's manifest (exposed to LLM clients) requires a human-readable description of what the tool does.

Source

Thrown at internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go:129

}

type Config struct {
	tools.ConfigBase `yaml:",inline"`
	Type             string                 `yaml:"type" validate:"required"`
	Source           string                 `yaml:"source" validate:"required"`
	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)
	}

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

// validate interface
var _ tools.Tool = Tool{}

type Tool struct {
	tools.BaseTool[Config]

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty description field to the tool's YAML config
2. If generating configs, ensure the description is always rendered
3. Run config validation before deploying to catch empty descriptions early

Example fix

// before
tools:
  my-tool:
    kind: bigquery-conversational-analytics
    source: my-bq-source
// after
tools:
  my-tool:
    kind: bigquery-conversational-analytics
    source: my-bq-source
    description: "Ask natural-language questions against BigQuery datasets"

func validateToolConfig(cfg map[string]any) error {
    desc, ok := cfg["description"].(string)
    if !ok || desc == "" {
        return fmt.Errorf("description is required for tool %v", cfg["name"])
    }
    return nil
}

tool, err := cfg.Initialize(ctx)
if err != nil {
    if strings.Contains(err.Error(), "description is required") {
        return fmt.Errorf("config error: add a 'description' field to tool %q", cfg.Name)
    }
    return err
}

When it happens

Trigger: Defining a bigqueryconversationalanalytics tool in a YAML config with no description field (or description: ""), causing Config.Initialize to return this error at server startup.

Common situations: Hand-edited toolbox YAML omitting the description; templated configs that drop optional-looking fields; copy-paste of a tool block that loses the description line.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• description is required for tool %q
• expected allowedDataset to have at least 2 parts (project.da
• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa
• `introspectionParamName` is not allowed when `mcpEnabled` is

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