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

Add a meaningful `description:` to the tidb-sql tool config.

description is required for tool %q

Error message

description is required for tool %q

What it means

Initialize rejects a tool configuration whose 'description' field is empty. Description is mandatory for this tool type (it feeds the LLM tool manifest), so the error fires during startup when the tools.yaml entry omits or leaves blank the 'description' key.

Source

Thrown at internal/tools/tidb/tidbsql/tidbsql.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.NewDestructiveAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: paramManifest, AuthRequired: cfg.AuthRequired},
			allParameters,
		),
	}, nil
}

// validate interface

View on GitHub (pinned to 8cc6e09de2)

Solutions

Add a meaningful `description:` to the tidb-sql tool config.
Verify the YAML nesting so the field reaches the Config struct.
Check templated descriptions for empty output.

Example fix

# before
kind: tidb-sql
source: my-tidb
statement: SELECT * FROM t WHERE id = ?
# after
kind: tidb-sql
source: my-tidb
description: "Get row from table t by id."
statement: SELECT * FROM t WHERE id = ?

Defensive patterns

Strategy: validation

Validate before calling

yq '.tools[] | select(.kind == "tidb-sql") | select(.description == null or .description == "")' tools.yaml

Type guard

func validTidbSQL(c tidbsql.Config) error {
    if c.Description == "" { return errors.New("description is required") }
    return nil
}

Try / catch

tool, err := cfg.Initialize(ctx)
if err != nil {
    return fmt.Errorf("tidb-sql tool invalid: %w", err)
}

Prevention

Make description mandatory in your config scaffolding scripts.
Add schema validation (JSON schema / yamllint custom rule) for tools.yaml.
Review templated fields for empty rendered output.

When it happens

Trigger: `tidb-sql` tool config missing `description:` or set to empty string; template rendering an empty value.

Common situations: Scaffolding many tools quickly and omitting description; bad YAML indentation; copying configs from tools that had description optional.

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/a200c779b9a97b92. Report an issue: GitHub.