feat(mcp): a machine-readable "next_steps" field beside the prose guard text #846

New issue

Open

opened 2026-10-20 16:51:01 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-20 16:51:01 +00:00

Owner

What happens

When a call fails a precondition, such as not authenticated, on the default branch, or a foreign primary, the error names the next step in prose. ADR 0026 already makes every guard text terminal or forwarding, so the exit is stated. But the caller must parse that prose to act on it.

Scope

This is not about parameter-name errors. ADR 0005 is clear that a wrong-name guess is fixed at the schema, so the first call lands and no retry is needed. This asks only for the genuine precondition and state failures, where a follow-up call is the correct path and the tool already knows it.

Proposal

Add a machine-readable next_steps field to the error output for those precondition failures: the concrete follow-up calls, structured, beside the existing prose that ADR 0026 requires. The prose stays; the field lets a caller act with no re-parse.

Acceptance criteria

A precondition or state failure (not authenticated, default-branch refusal, foreign-primary refusal, and the like) carries a machine-readable next_steps field in the error output.
The field lists the concrete follow-up calls.
The prose exit that ADR 0026 requires stays unchanged beside the field.
Parameter-name errors get no next_steps field (ADR 0005 keeps them a schema fix).

ADR 0026 (guard texts are terminal or forwarding), ADR 0005 (a wrong name is fixed at the schema, not in the error), #747 (first-call success).

## What happens When a call fails a precondition, such as not authenticated, on the default branch, or a foreign primary, the error names the next step in prose. ADR 0026 already makes every guard text terminal or forwarding, so the exit is stated. But the caller must parse that prose to act on it. ## Scope This is not about parameter-name errors. ADR 0005 is clear that a wrong-name guess is fixed at the schema, so the first call lands and no retry is needed. This asks only for the genuine precondition and state failures, where a follow-up call is the correct path and the tool already knows it. ## Proposal Add a machine-readable `next_steps` field to the error output for those precondition failures: the concrete follow-up calls, structured, beside the existing prose that ADR 0026 requires. The prose stays; the field lets a caller act with no re-parse. ## Acceptance criteria - A precondition or state failure (not authenticated, default-branch refusal, foreign-primary refusal, and the like) carries a machine-readable `next_steps` field in the error output. - The field lists the concrete follow-up calls. - The prose exit that ADR 0026 requires stays unchanged beside the field. - Parameter-name errors get no `next_steps` field (ADR 0005 keeps them a schema fix). ## Related - ADR 0026 (guard texts are terminal or forwarding), ADR 0005 (a wrong name is fixed at the schema, not in the error), #747 (first-call success).

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#846

No description provided.

Rows
Columns