feat(tools): validate required params before dispatch

[John-Lussier]

What

Adds schema-driven required-parameter validation to the tool dispatch pipeline. When a model omits a required parameter from its tool call, the agent now receives an actionable error: "Missing required parameter(s): X. Please retry with all required parameters." instead of a confusing KeyError, silent None default, or partial result deep inside the tool handler.

Why

AIRTBench (Dreadnode, arXiv:2506.14682) found that ~21.7% of all agent execution failures are syntax/format errors — the single largest category. Failed runs cost 10× more than successful runs ($8.91 vs $0.89).

Hermes already has excellent type-level repair (trailing commas, Python None, unclosed braces via _repair_tool_call_arguments; string→int/bool/array coercion via coerce_tool_args; fuzzy tool-name matching via repair_tool_call). But there's no presence-level check — the schema's required array is never consulted before dispatch.

This fills that gap with a 15-line function (validate_required_params) that reads the tool's registered required array and returns any missing param names. It runs after coerce_tool_args and before the tool handler.

Where

model_tools.py:
  validate_required_params()   ← new function (after _coerce_boolean)
  dispatch_tool()              ← calls validate_required_params() right after coerce_tool_args

tests/model_tools/test_validate_required_params.py:  ← new test file (10 tests)

Design notes

• Zero overhead for unaffected paths: returns [] immediately for tools with no schema, no required array, or unknown tools.
• Runs after coercion: coerce_tool_args has already fixed type mismatches (string→int, etc.) before this check runs.
• Key-existence only: a param set to None counts as "present" — this is presence validation, not nullability validation.
• Error format matches existing patterns: returns {"error": "..."} JSON string, same as other pre-dispatch rejections.
• Uses isolated ToolRegistry in tests to avoid polluting the global registry.

Verification

python -m pytest tests/model_tools/test_validate_required_params.py -v
# 10 passed

python -m pytest tests/run_agent/test_tool_arg_coercion.py tests/run_agent/test_repair_tool_call_arguments.py -v
# 98 passed (no regressions)

[teknium1]

Thanks for targeting a real dispatch gap: current model_tools.py:1065-1068 has no generic check of schema required fields before registry execution.

Problems

• The new check at model_tools.py:1103 runs before tool-request middleware. That middleware is explicitly allowed to replace effective arguments before execution (hermes_cli/middleware.py:125-155; current dispatcher applies it at model_tools.py:1146-1162). A middleware that supplies a required field will be rejected too early; later execution middleware can also alter the arguments passed to registry.dispatch().
• The added tests call only validate_required_params() directly. They do not cover handle_function_call() or either middleware boundary.

Suggested changes

• Validate the final arguments immediately before registry.dispatch() and add integration tests for request middleware adding a required field and execution middleware removing one.
• Clarify whether agent-level dispatches are in scope: agent/tool_executor.py:1215-1248 bypasses handle_function_call() even though tools/memory_tool.py:1127 has a root required field.

Automated hermes-sweeper review.

[teknium1]

Blocking: this validates before tool_request middleware, but that middleware may replace effective arguments before execution. Validate at the final dispatch boundary instead, so middleware can supply required fields and later execution middleware cannot remove them undetected.

[John-Lussier]

Fixed in e039765. Required-param validation now runs at the final execution boundary immediately before registry dispatch, after tool-request middleware and inside the tool-execution middleware chain. Request middleware can supply a required field; execution middleware removing one now returns the actionable validation error without calling the handler. I also included agent-level tools in scope for both sequential and concurrent paths (including memory) and added integration coverage for all four boundaries. Verification: 155 focused tests passed; git diff --check passed.

[John-Lussier]

Review feedback is addressed in the current head e039765c78 (fix(tools): validate final middleware arguments):

• Validation now runs on the final effective arguments immediately before registry.dispatch(), after request and execution middleware have run.
• Added integration tests proving request middleware can add a required param and execution middleware cannot remove one.
• Extended validation to agent-level sequential and concurrent dispatch paths (agent/tool_executor.py and agent/agent_runtime_helpers.py).

Tests: test_validate_required_params.py expanded; test_model_tools.py updated; compile and git diff --check clean.