fix(core): surface helpful error when tool call arguments fail to JSON.parse

[devteamaegis]

Summary

When `coerceMessageLikeToMessage` receives an OpenAI-style tool call whose `function.arguments` is malformed JSON, the bare `JSON.parse` call inside `_coerceToolCall` (libs/langchain-core/src/messages/utils.ts:198) throws a generic `SyntaxError` with no context: no tool name, no tool call ID, no raw payload. Models do occasionally emit malformed JSON in tool arguments (most commonly when streaming and a chunk is mishandled), so this surfaces as a hard-to-debug exception in user code.

The sibling helper `defaultToolCallParser` in `messages/tool.ts:326` already handles this case by catching `JSON.parse` failures and routing to `invalid_tool_call` — the divergence is only in this one code path.

Fix

Wrap `JSON.parse` in `_coerceToolCall` with a try/catch that re-throws using `addLangChainErrorFields` and includes the tool name, the tool call id, and the raw arguments. Same `MESSAGE_COERCION_FAILURE` code as the sibling unrecognized-shape branch a few lines below.

Diff:

```diff

• return {

•  id: toolCall.id,
  

•  args: JSON.parse(toolCall.function.arguments),
  

•  name: toolCall.function.name,
  

•  type: \"tool_call\",
  

• };

• const name = toolCall.function.name;
• const rawArgs = toolCall.function.arguments;
• let args: Record<string, unknown>;
• try {

•  args = JSON.parse(rawArgs);
  

• } catch (cause) {

•  throw addLangChainErrorFields(
  

•    new Error(\`Failed to parse tool call arguments for \"\${name}\" (id=\${toolCall.id}): \${(cause as Error)?.message ?? cause}. Raw arguments: \${rawArgs}\`),
  

•    \"MESSAGE_COERCION_FAILURE\"
  

•  );
  

• }
• return { id: toolCall.id, args, name, type: "tool_call" };
  ```

Test

Two new vitest cases in `libs/langchain-core/src/messages/tests/message_utils.test.ts`:

1. `throws a helpful error when OpenAI-format tool call arguments are malformed` — passes a trailing-comma payload and asserts the error message contains the tool name, the id, and the raw JSON.
2. `still parses valid OpenAI-format tool call arguments` — regression guard.

`npx vitest run src/messages/tests/message_utils.test.ts` → 25 passed.

Novelty

`gh search prs --repo langchain-ai/langchainjs _coerceToolCall JSON.parse` returns no matches. No open PR touches this block.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e8267c8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR