Bug: sessions_send schema encourages invalid calls by exposing sessionKey and label as independent optionals

Summary

sessions_send rejects requests when both sessionKey and label are present, but the model-facing tool schema exposes them as separate optional fields with no mutual-exclusion guidance or normalization. In practice, models often populate both fields when they know both, which leads to avoidable runtime failures.

Runtime error

Provide either sessionKey or label (not both).

Why this happens

The tool contract currently makes all of these look independently optional:

• sessionKey
• label
• agentId

The description says the tool can send by session key or label, but the schema does not strongly indicate:

• that sessionKey and label are mutually exclusive
• that sessionKey should be preferred when known
• that agentId is only useful with label-based resolution

As a result, a model may emit something like:

{
  "sessionKey": "agent:example:discord:channel:123",
  "label": "Example Agent",
  "agentId": "example",
  "message": "test",
  "timeoutSeconds": 5
}

That payload is semantically unambiguous to a human, but it fails at runtime.

Expected behavior

Either of these would be reasonable:

1. Preferred: improve the schema/tool metadata so the model is guided to emit only one addressing mode.
2. Also helpful: executor-side normalization so that if both are present, sessionKey wins and label is ignored.

Actual behavior

The tool fails hard with:

Provide either sessionKey or label (not both).

Impact

This makes cross-session messaging unnecessarily brittle, especially in cases where:

• a prior discovery step returned both a session key and a human-readable label
• the model tries to be helpful by filling in all known addressing fields
• existing docs or local instructions are imperfect

Suggested fix

Option A — schema guidance

Add explicit field descriptions / guidance such as:

• sessionKey: preferred when known; do not also provide label
• label: use only when sessionKey is not available
• agentId: optional helper for label resolution only

Option B — executor canonicalization

If both sessionKey and label are provided:

• prefer sessionKey
• ignore label
• continue normally

That seems like the safest normalization because sessionKey is already the most specific target.

Bonus docs issue observed

Some local/user-written examples may incorrectly use invalid parameter names like agent= or target= for sessions_send. The core tool docs should probably show a canonical example block using only the actual supported fields:

{
  "sessionKey": "agent:example:discord:channel:123",
  "message": "..."
}

and

{
  "label": "Example Agent",
  "agentId": "example",
  "message": "..."
}

Environment

Observed on a current 2026.4.x OpenClaw install.