googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Thrown by cloudstorage-move-object Config.Initialize when the tool config has no description. The description is required because it is published to the LLM through the MCP tool manifest, and the toolbox rejects building the tool without it.

Source

Thrown at internal/tools/cloudstorage/cloudstoragemoveobject/cloudstoragemoveobject.go:72

}

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"`
	Bucket           *string                `yaml:"bucket,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)
	}
	if cfg.Bucket != nil && *cfg.Bucket == "" {
		return nil, fmt.Errorf("bucket cannot be empty for tool %q", cfg.Name)
	}

	sourceObjectParam := parameters.NewStringParameter(sourceObjectKey, "Full source object name (path) within the bucket, e.g. 'path/to/file.txt'.")
	destinationObjectParam := parameters.NewStringParameter(destinationObjectKey, "Full destination object name (path) within the same bucket, e.g. 'path/to/file.txt'.")
	allParameters := parameters.Parameters{}
	if cfg.Bucket == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(bucketKey, "Name of the Cloud Storage bucket containing the object to move."))
	}
	allParameters = append(allParameters, sourceObjectParam, destinationObjectParam)

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a meaningful non-empty 'description' to the tool config
2. Check template interpolation so the description is not empty after rendering
3. Reload the server to confirm the config now validates

Example fix

// before
  move-object:
    kind: cloudstorage-move-object
    source: my-gcs
// after
  move-object:
    kind: cloudstorage-move-object
    source: my-gcs
    description: Move or rename an object within a Cloud Storage bucket

if cfg.Description == "" {
    return fmt.Errorf("tool %q: description must be set in tools.yaml", cfg.Name)
}

When it happens

Trigger: A cloudstorage-move-object tool entry in tools.yaml omits 'description' or sets it to ""; Initialize runs at config load/server start.

Common situations: Writing a new move-object tool quickly and skipping the description; autogenerated or templated configs with empty description variables.

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
• description is required for tool %q
• bucket cannot be empty for tool %q
• description is required for tool %q

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