googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for the lookercreateagent tool validates that the required 'description' field is set in the tool's YAML configuration before constructing the tool. Because a tool's description is what the LLM sees, the library refuses to initialize a tool without one. The error includes the configured tool name so the offending YAML block is easy to find.

Source

Thrown at internal/tools/looker/lookercreateagent/lookercreateagent.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{}

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

	nameParameter := parameters.NewStringParameter("name", "The name of the agent.", parameters.WithStringDefault(""))
	descriptionParameter := parameters.NewStringParameter("description", "The description of the agent.", parameters.WithStringDefault(""))
	instructionsParameter := parameters.NewStringParameter("instructions", "The instructions (system prompt) for the agent.", parameters.WithStringDefault(""))
	sourcesParameter := parameters.NewArrayParameter(
		"sources",
		"Optional. A list of JSON-encoded data sources for the agent (e.g., [{\"model\": \"my_model\", \"explore\": \"my_explore\"}]).",
		parameters.NewMapParameter(
			"source",
			"A JSON-encoded source object with 'model' and 'explore' keys.",
			"string",
		),
		parameters.WithArrayRequired(false),
	)

	codeInterpreterParameter := parameters.NewBooleanParameter("code_interpreter", "Optional. Enables Code Interpreter for this Agent.", parameters.WithBooleanDefault(false))
	params := parameters.Parameters{nameParameter, descriptionParameter, instructionsParameter, sourcesParameter, codeInterpreterParameter}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty 'description' field to the looker-create-agent tool definition in the config YAML.
2. Validate the rendered config if using templating, ensuring the description is not interpolated to "".
3. Restart/reload the toolbox and confirm the tool initializes.

Example fix

# before
tools:
  create_agent:
    kind: looker-create-agent
    source: my-looker-instance
# after
tools:
  create_agent:
    kind: looker-create-agent
    source: my-looker-instance
    description: Creates a new Looker agent with the given name, description, and instructions.

// Go: pre-validate tool configs before loading
type toolCfg struct { Kind, Description string }
func validateToolCfg(c toolCfg) error {
    if c.Kind == "looker-create-agent" && strings.TrimSpace(c.Description) == "" {
        return fmt.Errorf("looker-create-agent %q: description is required", c.Kind)
    }
    return nil
}

if err := toolbox.LoadConfig(ctx, cfgPath); err != nil {
    if strings.Contains(err.Error(), "description is required for tool") {
        log.Fatalf("config error, add the missing description field: %v", err)
    }
    return err
}

When it happens

Trigger: Starting the toolbox (or reloading configs) with a looker-create-agent tool entry whose 'description' key is missing or set to an empty string.

Common situations: Hand-editing tools.yaml and omitting the description; templating that renders an empty description; converting a tool from another kind and forgetting required fields; CI config generation dropping 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
• error parsing argument: %w
• invalid role %q: must be 'user' or 'assistant'
• description is required for tool %q

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