googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

The cloud-storage-copyobject tool's Config.Initialize validates the YAML tool definition before constructing the tool. A tool must have a non-empty description, because the description is what the LLM/MCP client sees. If cfg.Description is empty the configuration is rejected at startup.

Source

Thrown at internal/tools/cloudstorage/cloudstoragecopyobject/cloudstoragecopyobject.go:74

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

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty `description` field to the tool's YAML config
2. Run `toolbox` config validation before deployment to catch it at CI time
3. Check YAML indentation — a mis-indented description key may parse into a different node and leave the field empty

Example fix

// before (tools.yaml)
- name: copy_object
  source: my-gcs
// after
- name: copy_object
  source: my-gcs
  description: Copies an object within or between Cloud Storage buckets

func validateCopyObjectTool(cfg map[string]any) error {
    d, _ := cfg["description"].(string)
    if strings.TrimSpace(d) == "" {
        return fmt.Errorf("tool %v: description is required", cfg["name"])
    }
    return nil
}

func hasDescription(cfg Config) bool { return cfg.Description != "" }

tool, err := cfg.Initialize(ctx)
if err != nil {
    if strings.Contains(err.Error(), "description is required") {
        return fmt.Errorf("config error in tools.yaml: %w", err)
    }
    return err
}

When it happens

Trigger: Defining a copy_object tool in tools.yaml (or via prebuilt config parsing) without the `description` field, so cfg.Description == "" when Initialize runs during server startup or config loading.

Common situations: Hand-editing tools.yaml and omitting description; templating/generation that drops empty fields; copying a tool block and deleting the description line.

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

• source_bucket cannot be empty for tool %q
• destination_bucket cannot be empty for tool %q
• description is required for tool %q
• description is required for tool %q
• doc %d: unexpected non-string key in input: %v

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