googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

The singlestore-execute-sql tool's Config.Initialize returns this error when the tool's `description` field is empty. Toolbox requires every tool to have a description because it is published in the MCP manifest that LLM clients use to decide when to invoke the tool. Initialization aborts before the tool is registered, so the server fails to start (or the tool fails to load) until a description is provided.

Source

Thrown at internal/tools/singlestore/singlestoreexecutesql/singlestoreexecutesql.go:71

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{}

// ToolConfigType returns the type of the tool configuration.
func (cfg Config) ToolConfigType() string {
	return resourceType
}

// Initialize sets up the Tool using the provided sources map.
func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
	if cfg.Description == "" {
		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
	}

	sqlParameter := parameters.NewStringParameter("sql", "The sql to execute.")
	allParameters := parameters.Parameters{sqlParameter}

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

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty `description:` field to the tool definition in tools.yaml.
2. Check YAML indentation so the `description` key is a direct child of the tool, not nested elsewhere.
3. If using env substitution for the description, verify the environment variable is set and non-empty.

Example fix

# before
tools:
  exec-sql:
    kind: singlestore-execute-sql
    source: singlestore-src
# after
tools:
  exec-sql:
    kind: singlestore-execute-sql
    source: singlestore-src
    description: Executes arbitrary SQL against SingleStore and returns results.

# check every tool block has a non-empty description before starting toolbox
# e.g. in CI:
# yq '.tools | to_entries | map(select(.value.description == null or .value.description == ""))' tools.yaml

func hasDescription(name, desc string) error {
    if desc == "" {
        return fmt.Errorf("tool %q is missing a description", name)
    }
    return nil
}

if err := toolbox.Start(ctx); err != nil {
    var cfgErr *config.ConfigError // or inspect the message
    if strings.Contains(err.Error(), "description is required for tool") {
        log.Fatalf("config error: %v — add a description to the named tool in tools.yaml", err)
    }
    log.Fatalf("toolbox failed to start: %v", err)
}

When it happens

Trigger: Declaring a `singlestore-execute-sql` tool in tools.yaml without a `description` field, or with `description: ""`, then starting Toolbox / loading the config.

Common situations: Minimal hand-written tools.yaml omitting optional-looking fields; templating that renders an empty description from a missing env var or parameter; YAML indentation errors so `description` falls under the wrong key and never reaches the Config.

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