What causes "%s.Params requires agent-readable When text" in larksuite/cli?

Write a concise agent-readable When sentence explaining when the params are required

%s.Params requires agent-readable When text

Error message

%s.Params requires agent-readable When text

What it means

Thrown when a conditional scope entry in Authorization.<identity>.ConditionalScopes declares Params but its When text is empty. Params narrow when a conditional scope applies, so an agent-readable When condition is mandatory to explain the requirement to AI agents and humans.

Source

Thrown at shortcuts/common/typed_compile_contract.go:64

			compiled.fields = append(compiled.fields, field)
		}
		keyBytes, _ := json.Marshal(definition)
		key := string(keyBytes)
		if _, duplicate := seen[key]; duplicate {
			return nil, fmt.Errorf("Input.Relations[%d] duplicates an earlier relation", i)
		}
		seen[key] = struct{}{}
		result = append(result, compiled)
	}
	return result, nil
}

func compileAuthorization(definition typedAuthorizationDefinition, fields []compiledInputField, fieldByName map[string]int) error {
	for identity, authorization := range definition.Identities {
		for i, conditional := range authorization.ConditionalScopes {
			path := fmt.Sprintf("Authorization.%s.ConditionalScopes[%d]", identity, i)
			if len(conditional.Params) > 0 && conditional.When == "" {
				return fmt.Errorf("%s.Params requires agent-readable When text", path)
			}
			seen := make(map[string]struct{}, len(conditional.Params))
			for j, param := range conditional.Params {
				if param == "" || param != strings.TrimSpace(param) {
					return fmt.Errorf("%s.Params[%d] must be a non-blank trimmed param", path, j)
				}
				fieldIndex, ok := fieldByName[param]
				if !ok {
					return fmt.Errorf("%s references unknown param --%s", path, param)
				}
				if fields[fieldIndex].cli.Hidden {
					return fmt.Errorf("%s references hidden param --%s; use a public canonical param", path, param)
				}
				if _, duplicate := seen[param]; duplicate {
					return fmt.Errorf("%s.Params contains duplicate param --%s", path, param)
				}
				seen[param] = struct{}{}
			}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Write a concise agent-readable When sentence explaining when the params are required
Remove the Params entries if no condition is actually needed

Example fix

// before
ConditionalScopes: []ConditionalScope{{Params: []string{"--doc-id"}}}
// after
ConditionalScopes: []ConditionalScope{{Params: []string{"--doc-id"}, When: "required when --doc-id targets a wiki document instead of a drive file"}}

Defensive patterns

Strategy: validation

Validate before calling

for _, cs := range scope.ConditionalScopes {
  if len(cs.Params) > 0 && strings.TrimSpace(cs.When) == "" {
    return fmt.Errorf("conditional scope with params needs When text")
  }
}

Try / catch

if err := common.CompileTypedDefinition(def); err != nil {
  return fmt.Errorf("conditional scope misconfigured: %w", err)
}

Prevention

Write When text at the same time you add Params — never leave a TODO
Review authorization blocks for agent readability in code review
Make a lint/test that fails on empty When with params

When it happens

Trigger: Defining ConditionalScopes[{Params: ["--x"], When: ""}] — params present, When omitted or blank.

Common situations: Filling in Params and leaving When for later; scaffolding a new conditional scope; stripping When text during a refactor.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/87e7635aaede032e. Report an issue: GitHub.