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

Add a non-empty 'description' field to the tool's YAML config.

description is required for tool %q

Error message

description is required for tool %q

What it means

Firebird execute-sql tool configuration validation: Config.Initialize rejects the tool when the description field is empty. The description is mandatory because it is surfaced to LLM clients as the tool's manifest description. The error names the affected tool via cfg.Name.

Source

Thrown at internal/tools/firebird/firebirdexecutesql/firebirdexecutesql.go:66

	RunSQL(context.Context, string, []any) (any, error)
}

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"`
}

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

	sqlParameter := parameters.NewStringParameter("sql", "The sql to execute.")
	params := parameters.Parameters{sqlParameter}

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

var _ tools.Tool = Tool{}

type Tool struct {

View on GitHub (pinned to 8cc6e09de2)

Solutions

Add a non-empty 'description' field to the tool's YAML config.
Ensure env substitution (e.g., ${VAR}) for description is not resolving to an empty string.
Re-run toolbox after fixing the config.

Example fix

// before
tools:
  execute_sql:
    kind: firebird-execute-sql
    source: my-firebird
// after
tools:
  execute_sql:
    kind: firebird-execute-sql
    source: my-firebird
    description: Executes arbitrary SQL against Firebird.

Defensive patterns

Strategy: validation

Validate before calling

# Pre-validate the tool config before loading
import yaml, sys
cfg = yaml.safe_load(open('tools.yaml'))
for name, t in cfg.get('tools', {}).items():
    if t.get('kind') == 'firebird-execute-sql' and not t.get('description'):
        sys.exit(f"tool '{name}' is missing a description")

Try / catch

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

Prevention

Always include a description field when authoring tool configs.
Lint tool YAMLs for required fields (name, kind, source, description).
Avoid empty env substitutions for description.
Validate configs in CI with `toolbox --prebuilt` or a config dry-run.

When it happens

Trigger: A tools YAML config declares a firebird-execute-sql tool without a 'description' field (or with description: ''), then Initialize is called during config loading.

Common situations: Copy-pasting a tool config and forgetting the description; empty-string description from templating/env substitution; hand-written minimal configs omitting required fields.

Related errors

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