GLM-5.1: Claude Code Tool Discovery and System Role Compatibility Workaround

One-sentence takeaway

When using GLM-5.1 in Claude Code or a multi-Agent framework, you must explicitly inject tool_reference parsing rules into the system prompt to prevent tool deadlocks, and intercept the system role in messages[] to avoid HTTP 422 errors.

Use cases

• Suitable tasks: Using the Claude Code CLI, OpenCode, Cline, or Roo Code to drive GLM-5.1 through an Anthropic-compatible interface or local proxy for multi-tool, multi-agent collaboration tasks.

• Unsuitable tasks: Running complex workflows that include ToolSearch lazy-loaded tools directly with the native Anthropic client without any system-prompt constraints.

• Applicable model versions: GLM-5.1, GLM-5.2.

• Applicable clients, Agents, or APIs: Claude Code CLI (2.1.x+), Z.ai API (/api/anthropic), BigModel.cn API, local SGLang/vLLM proxies.

• Recommended reasoning levels and parameters: Standard Agent parameters; disable the client's unprocessed role: "system" injection, or disable ENABLE_TOOL_SEARCH.

Ready-to-use content

Tool-understanding system prompt for Claude Code / CLAUDE.md

Add the following content to the CLAUDE.md in the project root or to the global system prompt to fix the GLM-5.1 defect where it misinterprets tool_reference as “tool not found” and stops:

## Understanding tool_reference Response Type

When ToolSearch returns a response containing:
{"type": "tool_reference", "tool_name": "<ToolName>"}

This means the tool is now registered and available. You must proceed immediately to invoke the tool directly:
<ToolName>({ ...parameters... })

Never respond with "The tool search didn't return any tool" when a tool_reference block is present.

Claude Code environment variables and configuration workaround

Add the following configuration to the Claude Code configuration file ~/.claude/settings.json or to the environment to avoid ToolSearch loops and endpoint 422 validation failures:

# Option A: Disable lazy tool search directly through an environment variable (preload all tools)
export ENABLE_TOOL_SEARCH=false

# Option B: Configure the Anthropic-compatible endpoint
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-api-key"

Test/workflow steps

1. Configure GLM-5.1 as the backend model in Claude Code.

2. Trigger a task involving multiple agents or dynamic tool search (such as ultracode or Workflow).

3. Check the returned logs: if the prompt above has not been injected, GLM-5.1 will respond “tool not found” and terminate when it receives {"type": "tool_reference", "tool_name": "Workflow"}.

4. Inject the Markdown above into CLAUDE.md and run the task again to verify that GLM-5.1 correctly recognizes tool_reference and directly initiates a Workflow({...}) call.

5. If using a plugin that injects a SessionStart hook (such as superpowers), use local middleware to fold the system role messages in messages[] into the top-level system field to prevent the GLM endpoint from returning HTTP 422.

Original evidence and data

• GitHub Issue #76 records that when the ultracode workflow is triggered in Claude Code, GLM-5.1 cannot natively recognize Anthropic's tool_reference protocol block. In comparative tests, Claude Sonnet 4 and Xiaomi Memo handled it correctly, while GLM-5.1 terminated execution.

• GitHub Issue #74 records that Claude Code injects {"role": "system", "content": "..."} into the messages[] array. The official Anthropic endpoint folds it normally, but the GLM-compatible endpoint returns HTTP 422: Input should be 'user' or 'assistant'.

Applicability boundaries

• This workaround targets incompatibilities at the Anthropic protocol and tool-discovery layers; it cannot resolve underlying code-logic errors in the model itself.

• If the model backend is deployed on self-hosted SGLang/vLLM, you can upgrade directly to the latest branch containing the tool-parsing fix.

Source excerpt or observation (for compliant short quote only)

An Issue contributor noted: “GLM-5.1's training data does not appear to include the tool_reference response type... Adding explicit guidance about tool_reference in the system prompt enables GLM-5.1 to handle it correctly.”