googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

The singlestore-sql tool's Config.Initialize returns this error when the tool's `description` field is empty. Descriptions are mandatory because they appear in the tool's MCP manifest and guide LLM clients in tool selection; Toolbox refuses to initialize a tool without one. The error names the tool so the offending entry in tools.yaml is easy to find.

Source

Thrown at internal/tools/singlestore/singlestoresql/singlestoresql.go:76

	Parameters         parameters.Parameters  `yaml:"parameters"`
	TemplateParameters parameters.Parameters  `yaml:"templateParameters"`
	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 and returns a new Tool instance based on the provided configuration.
// It processes tool parameters and constructs the necessary manifests for tool operation.
// Returns an initialized Tool or an error if setup fails.
func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
	if cfg.Description == "" {
		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
	}

	allParameters, paramManifest, err := parameters.ProcessParameters(cfg.TemplateParameters, cfg.Parameters)
	if err != nil {
		return nil, err
	}

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

// validate interface

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a descriptive `description:` string to the singlestore-sql tool entry.
2. Verify the description key is at the tool level with correct indentation.
3. Ensure any templated/env-substituted description resolves to a non-empty value.

Example fix

# before
tools:
  my-sql-tool:
    kind: singlestore-sql
    source: singlestore-src
# after
tools:
  my-sql-tool:
    kind: singlestore-sql
    source: singlestore-src
    description: Run parameterized SQL queries against SingleStore.

tools:
  my-sql-tool:
    kind: singlestore-sql
    source: singlestore-src
    description: "Run SQL against SingleStore"  # required, non-empty

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 {
    if strings.Contains(err.Error(), "description is required for tool") {
        log.Fatalf("fix tools.yaml: %v", err)
    }
    log.Fatalf("toolbox failed: %v", err)
}

When it happens

Trigger: Loading a config containing a `singlestore-sql` tool with no `description` key or an empty-string description, triggering `fmt.Errorf("description is required for tool %q", cfg.Name)` in Initialize.

Common situations: Omitting description in minimal test configs; template/CI generation dropping the field; YAML structure mistakes (e.g. description nested under parameters or mis-indented) leaving cfg.Description empty.

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/6069a0ce36890e61. Report an issue: GitHub.