action-dispatched tools: required params and valid action/op values aren't in the schema, so first calls error-and-retry #716

New issue

Open

opened 2026-10-04 19:21:09 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-04 19:21:09 +00:00

Owner

What happens

The action-dispatched tools (ADR 0015) expose one flat input schema per tool. The valid action/op values, the per-action required params, and the canonical param names are not in that schema - they live in madt_help and the prose. So a call made without first reading madt_help for that exact action gets a server-side error and a retry. Each miss is a wasted round-trip (turns and tokens), which is the cost the schema should remove.

Evidence (one session)

madt_search with no action -> required: action; and with query= -> unknown argument query (valid: ..., q, ...).
madt_branch_create name=... -> unknown argument name (did you mean base?) - name= was renamed to branch= (a rename old habits and docs still miss).
madt_issues action=body with no op -> required field op is empty.
madt_issues action=delete -> not a valid action (only discoverable by hitting the enum).

The error messages are good - they name the valid args, so each miss self-corrects in one step. But the step is a round-trip a self-sufficient schema would save.

Why it matters

"Call these tools directly" is the stated agent contract, yet the schema alone is not enough to call them correctly - so an agent either pre-reads help for every action or errors, both round-trips. ADR 0005 (parameter-name ergonomics) and ADR 0008 (the registry renders action/op summaries inline) aim at exactly this; the cases above are where it is not yet realized.

Possible fixes

Encode action and op as JSON-Schema enums of their valid values, so a bad value is rejected client-side before the round-trip.
Surface per-action required params in the schema where it can (conditional subschemas keyed on action), or at least in each action's inline summary.
Keep param names canonical and stable across actions; flag renames (name -> branch) loudly.

Agent-call-form drift (hook and MCP text naming tools in a form the agent cannot call): #706.

## What happens The action-dispatched tools (ADR 0015) expose one flat input schema per tool. The valid `action`/`op` values, the per-action required params, and the canonical param names are not in that schema - they live in `madt_help` and the prose. So a call made without first reading `madt_help` for that exact action gets a server-side error and a retry. Each miss is a wasted round-trip (turns and tokens), which is the cost the schema should remove. ## Evidence (one session) - `madt_search` with no `action` -> `required: action`; and with `query=` -> `unknown argument query (valid: ..., q, ...)`. - `madt_branch_create name=...` -> `unknown argument name (did you mean base?) - name= was renamed to branch=` (a rename old habits and docs still miss). - `madt_issues action=body` with no `op` -> `required field op is empty`. - `madt_issues action=delete` -> not a valid action (only discoverable by hitting the enum). The error messages are good - they name the valid args, so each miss self-corrects in one step. But the step is a round-trip a self-sufficient schema would save. ## Why it matters "Call these tools directly" is the stated agent contract, yet the schema alone is not enough to call them correctly - so an agent either pre-reads help for every action or errors, both round-trips. ADR 0005 (parameter-name ergonomics) and ADR 0008 (the registry renders action/op summaries inline) aim at exactly this; the cases above are where it is not yet realized. ## Possible fixes - Encode `action` and `op` as JSON-Schema enums of their valid values, so a bad value is rejected client-side before the round-trip. - Surface per-action required params in the schema where it can (conditional subschemas keyed on `action`), or at least in each action's inline summary. - Keep param names canonical and stable across actions; flag renames (`name` -> `branch`) loudly. ## Related Agent-call-form drift (hook and MCP text naming tools in a form the agent cannot call): #706.

hexajon added the

enhancement

label

2026-10-04 19:21:09 +00:00

hexajon referenced this issue

2026-10-09 19:56:24 +00:00

bug(mcp): madt_finish description omits the required title (and summary) params #746

hexajon referenced this issue

2026-10-13 16:59:00 +00:00

feat(help): address madt_help by action, not only by whole tool #754