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

Add a non-empty description field to the looker-health-analyze tool entry in tools.yaml.

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for the looker-health-analyze tool requires a non-empty Description field; it validates this before building parameters and fails fast with this error. The description is what the MCP server advertises to LLM clients, so an empty one makes the tool unusable. This is a configuration-time validation error, not a runtime failure.

Source

Thrown at internal/tools/looker/lookerhealthanalyze/lookerhealthanalyze.go:76

}

type Config struct {
	tools.ConfigBase `yaml:",inline"`
	Type             string                 `yaml:"type" validate:"required"`
	Source           string                 `yaml:"source" validate:"required"`
	Parameters       map[string]any         `yaml:"parameters"`
	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
}

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)
	}

	actionParameter := parameters.NewStringParameter("action", "The analysis to run. Can be 'projects', 'models', or 'explores'.", parameters.WithStringRequired(true))
	projectParameter := parameters.NewStringParameter("project", "The Looker project to analyze (optional).", parameters.WithStringRequired(false))
	modelParameter := parameters.NewStringParameter("model", "The Looker model to analyze (optional).", parameters.WithStringRequired(false))
	exploreParameter := parameters.NewStringParameter("explore", "The Looker explore to analyze (optional).", parameters.WithStringRequired(false))
	timeframeParameter := parameters.NewIntParameter("timeframe", "The timeframe in days to analyze.", parameters.WithIntDefault(90))
	minQueriesParameter := parameters.NewIntParameter("min_queries", "The minimum number of queries for a model or explore to be considered used.", parameters.WithIntDefault(0))

	allParameters := parameters.Parameters{
		actionParameter,
		projectParameter,
		modelParameter,
		exploreParameter,
		timeframeParameter,
		minQueriesParameter,
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Add a non-empty description field to the looker-health-analyze tool entry in tools.yaml.
Check YAML indentation so the description is nested under the correct tool key.
Validate the config by loading the toolbox (go run . ) before deploying.
If constructing Config in code, set cfg.Description before calling Initialize.

Example fix

// before (tools.yaml)
tools:
  my_health_analyze:
    kind: looker-health-analyze
    source: my-looker-instance
// after
tools:
  my_health_analyze:
    kind: looker-health-analyze
    source: my-looker-instance
    description: Analyzes Looker projects, models, and explores for health issues.

Defensive patterns

Strategy: validation

Validate before calling

cfg := lookerhealthanalyze.Config{Name: "my_analyze"}
if cfg.Description == "" {
    return errors.New("description is required for looker-health-analyze tools")
}
_, err := cfg.Initialize(context.Background())

Try / catch

tool, err := cfg.Initialize(ctx)
if err != nil && strings.Contains(err.Error(), "description is required") {
    return fmt.Errorf("tools.yaml: add description for tool %q", cfg.Name)
}

Prevention

Always include description for every tool block in tools.yaml
Use a YAML schema/linter to enforce required fields
Copy tool entries from the official docs templates
Load the toolbox locally before deploying to catch config errors

When it happens

Trigger: Declaring a looker-health-analyze tool in tools.yaml (or constructing Config in Go) without setting the description field, then calling Initialize.

Common situations: Hand-edited YAML where the description key was forgotten or left blank, YAML indentation issues that drop the key, or generating configs from templates that omit optional-looking fields.

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

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