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

Add a meaningful non-empty `description` to the falkordb-cypher tool entry

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for the falkordb-cypher tool rejects the tool when `cfg.Description` is empty. The description is mandatory because it becomes the tool manifest shown to LLM clients; without it Initialize returns an error and the tool cannot be registered.

Source

Thrown at internal/tools/falkordb/falkordbcypher/falkordbcypher.go:69

type Config struct {
	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"`
	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.NewReadOnlyAnnotations),
			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

Add a meaningful non-empty `description` to the falkordb-cypher tool entry
Confirm the description key is correctly indented under the tool, not the source section
Avoid values that YAML coerces oddly; quote the description text
Reload and confirm the tool loads without the Initialize error

Example fix

// before (tools.yaml)
tools:
  cypher:
    kind: falkordb-cypher
    source: falkordb
// after
tools:
  cypher:
    kind: falkordb-cypher
    source: falkordb
    description: Executes a Cypher query on the FalkorDB graph database.

Defensive patterns

Strategy: validation

Validate before calling

for name, t := range cfg.Tools {
    if strings.TrimSpace(t.Description) == "" {
        return fmt.Errorf("tool %q (falkordb-cypher) needs a description", name)
    }
}

Type guard

func descriptionPresent(t ToolEntry) bool { return t.Description != nil && *t.Description != "" }

Try / catch

if _, err := cfg.Initialize(ctx); err != nil {
    if strings.Contains(err.Error(), "description is required") {
        // point the user at the offending tool name in the message
        return configFixError{err}
    }
    return err
}

Prevention

Treat description as a required field in every tool template
Run a YAML linter with a custom schema requiring tool.description
Avoid YAML anchors that may resolve to empty strings
Capture the error's %q tool name to locate the offending entry quickly

When it happens

Trigger: A tools.yaml entry with kind `falkordb-cypher` that has no `description` key or sets it to the empty string.

Common situations: Writing a first FalkorDB tools.yaml from memory and omitting description; a YAML alias/anchor resolving to an empty value; batch-generated configs where the description column was blank.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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