googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for cloudhealthcaregetfhirstore requires a non-empty Description; because Config embeds the shared base where name may be set independently, a tool declared without a description fails fast at initialization. This guarantees every registered tool exposes an LLM-facing description.

Source

Thrown at internal/tools/cloudhealthcare/cloudhealthcaregetfhirstore/cloudhealthcaregetfhirstore.go:69

}

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"`
}

// 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)
	}

	params := buildParams(false)
	return Tool{
		BaseTool: tools.NewBaseTool(
			cfg,
			tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: params.Manifest(), AuthRequired: cfg.AuthRequired},
			params,
		),
	}, nil
}

// validate interface
var _ tools.Tool = Tool{}

type Tool struct {
	tools.BaseTool[Config]

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a 'description' field to the tool's entry in tools.yaml.
2. Check YAML key spelling/indentation so the description lands in the tool's mapping.
3. When building Config in Go, set Description before calling Initialize.
4. Validate config with the toolbox CLI (config check/startup parse) before deploying.

Example fix

// before (tools.yaml)
  get-fhir-store:
    kind: cloudhealthcare-get-fhir-store
    source: my-healthcare-source
// after
  get-fhir-store:
    kind: cloudhealthcare-get-fhir-store
    source: my-healthcare-source
    description: Gets a FHIR store by name from a Cloud Healthcare dataset.

if strings.TrimSpace(cfg.Description) == "" {
    return errors.New("tool 'cloudhealthcare-get-fhir-store' is missing a description")
}

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

tool, err := cfg.Initialize(ctx)
if err != nil && strings.Contains(err.Error(), "description is required") {
    return nil, fmt.Errorf("tools.yaml: add a description for tool %q", cfg.Name)
}

When it happens

Trigger: Calling Initialize on a Config whose Description field is empty — typically a tools.yaml entry that omits the 'description' field, or YAML indentation that puts description under the wrong key.

Common situations: Hand-written tools.yaml missing description; description typo'd (e.g. 'descriptions'); programmatic Config construction leaving Description zero-valued; prebuilt-config regeneration dropping the field.

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
• error parsing argument: %w
• invalid role %q: must be 'user' or 'assistant'
• 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/e102af9a4674a2bb. Report an issue: GitHub.