googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Configuration-time validation in Initialize: the cloudstorage-download-object tool entry in tools.yaml has no description. Toolbox refuses to register tools without a description because it is what the LLM sees in the tool manifest.

Source

Thrown at internal/tools/cloudstorage/cloudstoragedownloadobject/cloudstoragedownloadobject.go:76

	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"`
	DestinationDir   *string                `yaml:"destination_dir,omitempty"`
	Overwrite        *bool                  `yaml:"overwrite,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)
	}
	if cfg.Bucket != nil && *cfg.Bucket == "" {
		return nil, fmt.Errorf("bucket cannot be empty for tool %q", cfg.Name)
	}
	if cfg.DestinationDir != nil {
		if *cfg.DestinationDir == "" {
			return nil, fmt.Errorf("destination_dir cannot be empty for tool %q", cfg.Name)
		}
		if _, err := cloudstoragecommon.ValidateLocalPath(*cfg.DestinationDir); err != nil {
			return nil, fmt.Errorf("destination_dir is invalid for tool %q: %w", cfg.Name, err)
		}
	}

	objectParam := parameters.NewStringParameter(objectKey, "Full object name (path) within the bucket, e.g. 'path/to/file.txt'.")
	destinationDesc := "Absolute local filesystem path where the object will be written. Relative paths and paths containing '..' are rejected."
	if cfg.DestinationDir != nil {
		destinationDesc = "Relative path under the configured destination_dir where the object will be written. Absolute paths and paths that escape destination_dir are rejected."
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a meaningful description field to the tool config
2. Check that the description is correctly indented inside the tool's YAML mapping
3. If using Go Config structs, set Description before Initialize

Example fix

// before
tools:
  download-object:
    kind: cloudstorage-download-object
    source: my-gcs
    destination_dir: /tmp
// after
tools:
  download-object:
    kind: cloudstorage-download-object
    source: my-gcs
    description: Download an object from Cloud Storage to a local directory
    destination_dir: /tmp

if cfg.Description == "" {
    return errors.New("download-object: description is required")
}

if err := startToolbox(); err != nil {
    if strings.Contains(err.Error(), "description is required") {
        // add description to tools.yaml
    }
    log.Fatal(err)
}

When it happens

Trigger: tools.yaml defines a cloudstorage-download-object tool with no description field or description: "".

Common situations: Omitting description when adding the download tool to an existing config; YAML keys mis-nested under a different tool; generating configs programmatically without setting Description.

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

• description is required for tool %q
• bucket cannot be empty for tool %q
• destination_dir cannot be empty for tool %q
• description is required 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/97ed28a5c4f1c8e2. Report an issue: GitHub.