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

Add a non-empty 'description' to the firebird-sql tool config.

description is required for tool %q

Error message

description is required for tool %q

What it means

Firebird SQL tool configuration validation: Config.Initialize rejects the tool when the description field is empty. The description is required for the tool manifest exposed to LLM clients. The error includes the tool's configured name.

Source

Thrown at internal/tools/firebird/firebirdsql/firebirdsql.go:71

	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 non-empty 'description' to the firebird-sql tool config.
Check any env/parameter substitution feeding description isn't empty.
Reload the toolbox config after the fix.

Example fix

// before
  my_query:
    kind: firebird-sql
    source: my-firebird
// after
  my_query:
    kind: firebird-sql
    source: my-firebird
    description: Runs a parameterized Firebird SQL query.

Defensive patterns

Strategy: validation

Validate before calling

# Pre-flight check
for name, t in cfg.get('tools', {}).items():
    if t.get('kind') == 'firebird-sql' and not t.get('description'):
        raise SystemExit(f"{name}: description is required")

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "description is required") {
        return fmt.Errorf("fix tools.yaml: %w", err)
    }
    return err
}

Prevention

Include descriptions for every declared tool.
Add schema validation for tool configs (required keys).
Beware of empty template substitutions for description.
Test config load locally before deploying.

When it happens

Trigger: Declaring a firebird-sql tool in the tools config without a 'description' (or empty string) and loading the config, triggering Initialize.

Common situations: Omitting description in hand-authored YAML; templated description resolving to empty; converting configs from other tool kinds and dropping required fields.

Related errors

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