googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

This error is thrown by the Config.Initialize method of the mongodb-delete-one tool when the tool's Description field is empty. The library requires every tool to have a non-empty description because it is surfaced in the tool manifest to LLM clients. Configuration validation fails fast at Initialize time rather than at server startup or request time.

Source

Thrown at internal/tools/mongodb/mongodbdeleteone/mongodbdeleteone.go:74

	Source                  string                 `yaml:"source" validate:"required"`
	Database                string                 `yaml:"database" validate:"required"`
	Collection              string                 `yaml:"collection"`
	CollectionAllowedValues []string               `yaml:"collectionAllowedValues"`
	FilterPayload           string                 `yaml:"filterPayload" validate:"required"`
	FilterParams            parameters.Parameters  `yaml:"filterParams"`
	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 := slices.Concat(cfg.FilterParams)

	if err := mongodbcommon.ValidateCollectionConfig(cfg.Collection, cfg.CollectionAllowedValues); err != nil {
		return nil, err
	}
	allParameters = mongodbcommon.WithRuntimeCollectionParam(cfg.Collection, cfg.CollectionAllowedValues, allParameters)

	if err := parameters.CheckDuplicateParameters(allParameters); err != nil {
		return nil, err
	}

	paramManifest := allParameters.Manifest()
	if paramManifest == nil {
		paramManifest = make([]parameters.ParameterManifest, 0)
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty description field to the tool's YAML config entry.
2. If building Config in Go, set cfg.Description before calling Initialize.
3. Verify the description key is correctly indented/named in YAML so it deserializes into the Description field.

Example fix

# before
tools:
  delete-one-doc:
    kind: mongodb-delete-one
    source: my-mongo
    collection: users
# after
tools:
  delete-one-doc:
    kind: mongodb-delete-one
    source: my-mongo
    collection: users
    description: Deletes a single document from the users collection by filter.

// Go: validate before Initialize
if cfg.Description == "" {
    return fmt.Errorf("tool %q: description must be non-empty", cfg.Name)
}
_ = cfg.Initialize(context.Background())

// Go: ensure description is present on the decoded config
func hasDescription(c mongodbdeleteone.Config) bool { return c.Description != "" }

tool, err := cfg.Initialize(context.Background())
if err != nil && strings.Contains(err.Error(), "description is required") {
    // fall back to a default description and retry
    cfg.Description = "Default tool description"
    tool, err = cfg.Initialize(context.Background())
}

When it happens

Trigger: Calling Initialize() on a mongodbdeleteone.Config whose Description field is the empty string, e.g. a YAML tool definition that omits the description field or sets it to "".

Common situations: Hand-written tools.yaml missing the description key; programmatically building Config structs and forgetting Description; template/tool generation code that leaves description blank; renaming config fields so the description no longer deserializes into the struct.

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

• description is required for tool %q
• description is required for tool %q
• only one of 'collection' or 'collectionAllowedValues' can be
• description is required for tool %q
• invalid source for %q tool: source %q is not a compatible ty

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