googleapis/mcp-toolbox · error

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/valkey/valkey.go:68

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

	return Tool{
		BaseTool: tools.NewBaseTool(
			cfg,
			tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: cfg.Parameters.Manifest(), AuthRequired: cfg.AuthRequired},
			cfg.Parameters,
		),
	}, 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' to the valkey tool config in tools.yaml
2. Verify the YAML key is 'description' and not misspelled or wrongly indented
3. If building Config in code, set Description before Initialize

Example fix

# before
tools:
  valkey-sql:
    kind: valkey-execute-sql
    source: my-valkey
# after
tools:
  valkey-sql:
    kind: valkey-execute-sql
    source: my-valkey
    description: Executes Valkey commands against the source

if cfg.Description == "" {
    return fmt.Errorf("valkey tool %q requires a description", cfg.Name)
}

tool, err := cfg.Initialize(ctx)
if err != nil && strings.Contains(err.Error(), "description is required") {
    // add 'description:' to the valkey tool entry in tools.yaml
}

When it happens

Trigger: Defining any valkey tool (e.g. valkey-execute-sql) in tools.yaml without a 'description' field, or calling Config.Initialize with cfg.Description == ""; tests explicitly exercise this path via TestFailInitialization-style setups.

Common situations: Hand-written configs missing the field; templated config generation producing empty descriptions; upgrading and adding new valkey tools without filling in the description.

Related errors

• description is required for tool %q
• invalid source for %q tool: source %q is not a compatible ty
• description is required for tool %q
• --name is required unless --group or --toolset is set, or ex
• invalid ipType %s

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