openclaw - 💡(How to fix) Fix message tool: `message` body param schema-optional but runtime-required, causing silent LLM field-drop on send [1 participants]

Summary

message.send has a latent schema/runtime mismatch that causes models to omit the body text on otherwise valid calls. The tool returns message required and the agent has no way to recover without an out-of-band hint.

Mismatch

Schema declares the body optional — src/agents/tools/message-tool.ts:88:

function buildSendSchema(options: { includeInteractive: boolean }) {
  const props: Record<string, TSchema> = {
    message: Type.Optional(Type.String()),
    ...
  };
}

Runtime requires it — src/infra/outbound/message-action-runner.ts:484:

let message =
  readStringParam(params, "message", {
    required:
      !mediaHint && !hasButtons && !hasCard && !hasComponents && !hasInteractive && !hasBlocks,
    allowEmpty: true,
  }) ?? "";

So a text-only send call with the message field missing is schema-valid but runtime-rejected.

Why this bites on real calls

The body field name (message) collides with the tool name (message). When we ask an LLM to call message(action: \"send\", ..., message: \"hello\"), the model regularly drops the inner message field — producing { action: \"send\", channel: ..., target: ... } with no body. Because the schema marks that field optional, there is no validator signal to push the model to include it; the failure only surfaces at runtime.

We see this on Claude, but the shape of the problem is provider-agnostic — it's a tool-schema design issue.

Reproduction

Anthropic claude-opus-4-7, discorduser plugin, text-only send:

message(action: \"send\", channel: \"discorduser\", target: \"channel:<id>\", message: \"test\", accountId: \"alice\")

~50% of the time the model emits:

message(action: \"send\", channel: \"discorduser\", target: \"channel:<id>\", accountId: \"alice\")

Runtime returns message required. Retrying in the same turn doesn't reliably fix it because the model has already committed the schema it thinks the tool wants.

Suggested fixes (either/or)

A. Tighten the schema to match runtime. Use a discriminated union on action so send without any media/card/components/interactive/blocks actually requires message. This is the right fix because it gives LLMs a correctness signal they can use during call generation.

B. Accept a disambiguating alias. Teach readStringParam (or the send runner specifically) to fall back to body, text, or content if message is missing. This follows the same pattern already used in buildReactionSchema at lines 151–157, where messageId is aliased as message_id explicitly for "tool-schema discoverability in LLMs." A similar note there says:

Intentional duplicate alias for tool-schema discoverability in LLMs.

An alias is cheaper to ship and backwards-compatible. I'd advocate doing both — alias now, discriminated-union later.

Impact

Every puppet / shared-session deployment that uses message.send for plain text hits this. Workarounds today are either patching the runner downstream or prompt-engineering the model to always include message:, neither of which scales.

Happy to send a PR for the alias fix if the direction sounds right.

Environment: openclaw v2026.3.1, discorduser plugin, claude-opus-4-7