OpenClaw Issue Report: Agent-to-Agent Communication Tool Parameter Conflicts

Summary

When attempting to use sessions_send and message tools for agent-to-agent communication, LLMs consistently add conflicting optional parameters, causing tool execution to fail. This appears to be a systematic issue with how optional parameters are defined in tool schemas.

Environment

• OpenClaw Version: Latest (as of 2026-03-09)
• Model: rightcode-codex/gpt-5.4, volcengine-plan/kimi-k2.5, deepseek/deepseek-reasoner
• Platform: Linux (WSL2)
• Configuration: Multiple agents with agent-to-agent communication enabled

Issue 1: sessions_send Tool Parameter Conflict

Problem

When instructing an agent to use sessions_send to send a message to another agent, the LLM consistently provides both sessionKey and label parameters, triggering a validation error.

Error Message

{
  "runId": "...",
  "status": "error",
  "error": "Provide either sessionKey or label (not both)."
}

Tool Schema

const SessionsSendToolSchema = Type.Object({
    sessionKey: Type.Optional(Type.String()),
    label: Type.Optional(Type.String({minLength: 1, maxLength: 64})),
    agentId: Type.Optional(Type.String({minLength: 1, maxLength: 64})),
    message: Type.String(),
    timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 }))
});

Tool Description

"Send a message into another session. Use sessionKey or label to identify the target."

Reproduction Steps

1. Configure multiple agents with agent-to-agent communication enabled:

   {
     "tools": {
       "agentToAgent": {
         "enabled": true,
         "allow": ["agent1", "agent2"]
       }
     }
   }

2. Instruct agent1 to send a message to agent2:

   Use sessions_send tool to send a message to agent2.
   Parameters:
   {
     "message": "Test message",
     "sessionKey": "agent:agent2:main"
   }
   

3. Observe that the LLM adds both sessionKey and label parameters

Expected Behavior

The LLM should use only sessionKey OR label, not both.

Actual Behavior

The LLM provides both parameters, causing the validation to fail with "Provide either sessionKey or label (not both)."

Root Cause Analysis

1. Schema Design: Both sessionKey and label are marked as Optional, with no mutual exclusion constraint
2. Tool Description Ambiguity: "Use sessionKey or label" can be interpreted as "you can use both"
3. LLM Behavior: LLMs tend to fill all optional parameters, believing "more information is safer"

Issue 2: message Tool Poll Parameter Conflict

Problem

When using the message tool with action: "send", the LLM adds poll-related parameters, triggering a validation error.

Error Message

Poll fields require action "poll"; use action "poll" instead of "send".

Reproduction Steps

1. Instruct an agent to send a message using the message tool:

   Use message tool with:
   {
     "action": "send",
     "channel": "feishu",
     "to": "ou_xxx",
     "message": "Test message"
   }
   

2. Observe that the LLM adds poll-related parameters (e.g., pollQuestion, pollOptions)

Expected Behavior

When action is "send", poll parameters should not be included.

Actual Behavior

The LLM adds poll parameters, causing validation to fail.

Root Cause Analysis

The message tool schema includes many optional poll-related parameters. The validation logic checks:

if (action === "send" && hasPollCreationParams(params)) 
    throw new Error("Poll fields require action \"poll\"; use action \"poll\" instead of \"send\".");

LLMs see these optional parameters and fill them, triggering the validation error.

Impact

• Agent-to-agent communication is effectively broken when using the built-in tools
• Users must resort to workarounds (file sharing, manual message forwarding)
• This affects multi-agent workflows and automation

Attempted Workarounds

1. Explicit Instructions

Provided detailed documentation instructing the LLM to use only specific parameters. Result: Failed - LLM still adds extra parameters.

2. Multiple Instruction Formats

Tried various instruction formats:

• JSON format with only required parameters
• Natural language with explicit "do not use X parameter"
• Step-by-step instructions

Result: All failed - LLM behavior is consistent across different models.

3. Alternative Tools

• feishu_chat: Does not support send action
• message: Has poll parameter conflict (Issue 2)

Result: No working alternative found.

Proposed Solutions

Solution 1: Schema-Level Mutual Exclusion (Recommended)

Use JSON Schema's oneOf or similar constructs to enforce mutual exclusion:

const SessionsSendToolSchema = Type.Object({
    message: Type.String(),
    timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 }))
}, {
    oneOf: [
        { required: ['sessionKey'], properties: { sessionKey: Type.String() } },
        { 
            required: ['label'], 
            properties: { 
                label: Type.String({minLength: 1, maxLength: 64}),
                agentId: Type.Optional(Type.String({minLength: 1, maxLength: 64}))
            } 
        }
    ]
});

Solution 2: Clearer Tool Description

Update the description to be more explicit:

"Send a message into another session. IMPORTANT: Use EITHER sessionKey OR label to identify the target, never both. If you have a sessionKey, do not provide label or agentId."

Solution 3: Separate Tools

Create two separate tools:

• sessions_send_by_key: Only accepts sessionKey
• sessions_send_by_label: Only accepts label and optional agentId

Solution 4: Parameter Filtering

Add a preprocessing step that removes conflicting parameters before validation:

// If sessionKey is provided, remove label and agentId
if (params.sessionKey) {
    delete params.label;
    delete params.agentId;
}

Solution 5: Action-Specific Schemas

For the message tool, use different schemas based on the action parameter:

if (action === "send") {
    // Use schema without poll parameters
} else if (action === "poll") {
    // Use schema with poll parameters
}

Additional Context

Tested Models

• rightcode-codex/gpt-5.4
• volcengine-plan/kimi-k2.5
• deepseek/deepseek-reasoner

All models exhibit the same behavior, suggesting this is a systematic issue with tool schema design rather than model-specific behavior.

Configuration Files

Agent configuration:

{
  "agents": {
    "entries": [
      {"id": "main", "workspace": "/path/to/main"},
      {"id": "finance_agent", "workspace": "/path/to/finance"}
    ]
  },
  "tools": {
    "profile": "full",
    "sessions": {"visibility": "all"},
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "finance_agent"]
    }
  }
}

Log Examples

2026-03-09T21:13:16.794+08:00 [tools] sessions_send failed: message required
2026-03-09T21:11:32.871+08:00 [tools] message failed: Poll fields require action "poll"; use action "poll" instead of "send".

Recommendation

I recommend implementing Solution 1 (Schema-Level Mutual Exclusion) combined with Solution 2 (Clearer Tool Description) as this addresses the root cause while maintaining backward compatibility.

For the message tool, Solution 5 (Action-Specific Schemas) would be most appropriate.

Related Issues

• Tool parameter validation
• LLM tool calling behavior
• Multi-agent communication

Workaround for Users

Until this is fixed, users can:

1. Use file-based communication between agents
2. Manually forward messages through the UI
3. Create custom wrapper tools with simplified schemas

Reporter: User via AI Assistant
Date: 2026-03-09
Priority: High (blocks core multi-agent functionality)