googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

The generic "http" tool requires a description because it is surfaced to LLM clients in the manifest. Config.Initialize fails with this error when an http tool in tools.yaml lacks a non-empty description field.

Source

Thrown at internal/tools/http/http.go:81

	Headers          map[string]string      `yaml:"headers"`
	RequestBody      string                 `yaml:"requestBody"`
	PathParams       parameters.Parameters  `yaml:"pathParams"`
	QueryParams      parameters.Parameters  `yaml:"queryParams"`
	BodyParams       parameters.Parameters  `yaml:"bodyParams"`
	HeaderParams     parameters.Parameters  `yaml:"headerParams"`
	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)
	}

	// Create a slice for all parameters
	allParameters := slices.Concat(cfg.PathParams, cfg.QueryParams, cfg.BodyParams, cfg.HeaderParams)

	// Verify no duplicate parameter names
	err := parameters.CheckDuplicateParameters(allParameters)
	if err != nil {
		return nil, err
	}

	// Create Toolbox manifest
	paramManifest := allParameters.Manifest()

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a meaningful non-empty "description" to the http tool entry in tools.yaml.
2. Check YAML indentation so "description" belongs to the tool mapping.
3. Add a config lint step that fails CI when any tool entry has an empty description.

Example fix

# before
fetch-users:
  type: http
  source: api-src
  path: /users
  method: GET
# after
fetch-users:
  type: http
  source: api-src
  path: /users
  method: GET
  description: Fetch a list of users from the API

// Validate all http tool entries before serving
for _, tool := range httpTools {
    if strings.TrimSpace(tool.Description) == "" {
        return fmt.Errorf("http tool %q requires a non-empty description", tool.Name)
    }
}

When it happens

Trigger: An http tool entry omits "description" or has it as an empty string; Initialize() is invoked while loading the toolbox configuration and returns this error, aborting startup of that tool.

Common situations: Rapid prototyping of HTTP tools where description is left as a TODO; YAML mis-indentation placing description at the wrong level; config generators emitting empty strings for optional-looking fields.

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
• 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/91dbdcd73f83078d. Report an issue: GitHub.