What causes "%d is above the maximum value" in googleapis/mcp-toolbox?

Resend with an integer <= the configured maxValue (see the tool's parameter manifest/description)

%d is above the maximum value

Error message

%d is above the maximum value

What it means

IntParameter.Parse rejects an integer because it exceeds the parameter's configured maxValue. The value parsed as a valid int but is larger than the ceiling tool authors set, typically to protect databases from oversized LIMITs or huge offsets. This is expected input validation, not a library fault.

Source

Thrown at internal/util/parameters/parameters.go:827

		out = int(newV)
	case json.Number:
		newI, err := newV.Int64()
		if err != nil {
			return nil, &ParseTypeError{p.Name, p.Type, v}
		}
		out = int(newI)
	}
	if !p.IsAllowedValues(out) {
		return nil, fmt.Errorf("%d is not an allowed value", out)
	}
	if p.IsExcludedValues(out) {
		return nil, fmt.Errorf("%d is an excluded value", out)
	}
	if p.MinValue != nil && out < *p.MinValue {
		return nil, fmt.Errorf("%d is under the minimum value", out)
	}
	if p.MaxValue != nil && out > *p.MaxValue {
		return nil, fmt.Errorf("%d is above the maximum value", out)
	}
	return out, nil
}

func (p *IntParameter) GetAuthServices() []ParamAuthService {
	return p.AuthServices
}

func (p *IntParameter) GetDefault() any {
	if p.Default == nil {
		return nil
	}
	return *p.Default
}

// Manifest returns the manifest for the IntParameter.
func (p *IntParameter) Manifest() ParameterManifest {
	// only list ParamAuthService names (without fields) in manifest

View on GitHub (pinned to 8cc6e09de2)

Solutions

Resend with an integer <= the configured maxValue (see the tool's parameter manifest/description)
Clamp the value client-side, e.g. min(maxValue, value)
If a higher ceiling is valid, raise maxValue in tools.yaml (or WithIntMaxValue) and redeploy the toolbox

Example fix

// before
params := map[string]any{"limit": 1000} // maxValue is 100
// after
params := map[string]any{"limit": 100}

Defensive patterns

Strategy: validation

Validate before calling

func validateMaxInt(v int, maxValue int) error {
    if v > maxValue {
        return fmt.Errorf("%d exceeds maximum %d", v, maxValue)
    }
    return nil
}
// usage: validateMaxInt(limit, 100)

Type guard

func withinMaxInt(v, maxValue int) bool { return v <= maxValue }

Try / catch

out, err := tool.Parse(params)
if err != nil && strings.Contains(err.Error(), "is above the maximum value") {
    // clamp: params["limit"] = maxValue from manifest and retry once
}

Prevention

Clamp limits/sizes client-side using maxValue from the tool manifest
Never assume an unbounded LIMIT; read the parameter manifest
State the maximum in the parameter description for LLM callers
Re-verify bulk scripts after maxValue is tightened in tools.yaml

When it happens

Trigger: Invoking a tool with an integer greater than maxValue configured via yaml 'maxValue:' or WithIntMaxValue. Example: maxValue 100 and the request passes 1000.

Common situations: LLMs picking generous limits like 10000; clients assuming no cap after the tool config added maxValue; bulk-export scripts requesting more rows per call than allowed.

Related errors

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