No structured way to signal a tool's refusal, distinct from success or a schema-validation error

[AshrafAhmed9]

Filing this from real friction hit building three apps for the WebMCP Challenge (one of them, Consequence, is built specifically around this issue).

The situation

execute() returns { content: [{ type: "text", text }] } regardless of whether the tool succeeded, was refused on purpose, or failed. There's no structured field distinguishing "I did the thing" from "I'm declining to do the thing, on purpose, and here's why."

We needed this because some of our tools enforce a real permission boundary: an agent is allowed to fill most fields on a form, but a few (attestations, signatures) can only be set by a human. When an agent calls our answer_question tool on one of those fields, the tool needs to refuse, clearly and on purpose, not silently no-op and not throw a generic error.

What we did instead

We return a normal-shaped success result whose text is a plain-language refusal message ("Refused: this field requires the human's own action"), and rely on the calling agent to read and respect that text. It works, but it's a convention we invented, not something the spec gives any structure to. An agent framework has no principled way to tell "the tool succeeded and this is the answer" apart from "the tool declined and this is why" without parsing prose.

Why this seems worth a spec-level answer

• A refusal is a different kind of outcome than a normal result, and calling code (or a UI showing tool-call history, which several of our apps do) benefits from being able to render it differently without string-sniffing.
• It's different from a schema-validation failure (which the runtime already rejects before execute even runs) — this is a tool voluntarily declining a well-formed, schema-valid call, because of business logic the schema can't express.
• Multiple entries in the awesome-webmcp list implement permission/authorization patterns where this would apply (ours included), so it's probably a recurring need, not a one-off.

Happy to be pointed at existing discussion if this has already been considered and rejected — didn't find one searching open issues.

[mlmrx]

One distinction in the current spec may help narrow this issue: a WebMCP execute callback is Promise<any>; it is not required to return an MCP { content: [...] } envelope (IDL). The normative imperative execution algorithm already treats fulfillment and rejection differently: fulfillment is JSON-serialized as a successful result, while a thrown exception/rejected promise takes the failure path (steps). So authors do not have to encode every refusal as a success-shaped text response.

The remaining gap is narrower, but real: the rejection reason r is discarded (apart from an optional console warning), and executeTool() maps the failure to a generic UnknownError (completion steps). Consequently, an in-page caller cannot distinguish a deliberate business-rule refusal from an operational exception, nor receive a structured refusal reason.

That suggests the design question is specifically whether and how WebMCP should preserve a typed refusal category/reason across the execution boundary, rather than whether success and failure can be distinguished at all. This also appears adjacent to #85 (execution lifecycle), #86 (result content model), and the authorization outcomes discussed in #165. A normative shape still needs group agreement, so I don't think a code change is safe yet.

[minjikim89]

We hit exactly this building a review tool on WebMCP, and ended up with two layers, both returned as ordinary tool results rather than thrown errors:

1. Schema failures: the page validates input itself (the browser does not, Who owns the validation layer? #92) and returns { ok:false, error:{ code:"INVALID_INPUT", problems:[…], inputSchema }, retrySafe:true }.
2. Deliberate refusals: OUT_OF_SCOPE (the person limited where the agent may write; carries the allowed ids), STALE_READ (the person changed the slide after the agent read it; carries changedSince), NOT_APPLICABLE (the slide type has no such field; carries the fields it does have). Each carries what the agent needs to recover, plus retrySafe.

The distinction that mattered for us is that a refusal is not a fault. The call was well-formed and the tool worked correctly by declining, and the agent's right next move differs in the two cases: fix the arguments, or go ask the person. Throwing conflates them, and the agent cannot tell from an exception whether retrying is even meaningful, hence retrySafe as a separate field rather than something inferred from the code.

Live: https://minjikim89.github.io/redline/ · shapes documented in https://github.com/minjikim89/redline/blob/main/docs/pattern.md

What we would want from the spec is a conventional envelope (ok, error.code, retrySafe) that hosts could surface uniformly. Today every site invents its own, so an agent has to learn each site's dialect before it can tell "you may not" from "that broke".

[AshrafAhmed9]

@mlmrx thanks, that's a clarifying distinction I'd missed, execute() not being required to return the MCP envelope means a refusal can already be a rejection rather than a success-shaped text blob. I'll probably rework Consequence's answer_question to throw on a human_only field instead of returning a plain-language refusal, since that's clearly closer to what the spec already supports.

But @minjikim89's comment is the part that makes me think this needs more than an implementation fix on our end. We ended up in almost the same place independently: not throwing, but returning an ordinary result with a structured outcome, because a refusal and an exception felt like different things to us too. Our version is cruder (a PermissionClass per field, and a tool that returns a plain refusal string when it hits a human_only one), but the shape rhymes with the ok/error.code/retrySafe envelope they built. Neither of us knew the other existed until this thread.

That's two unrelated apps solving "the call was valid and the tool worked correctly by declining" the same rough way, without the spec saying anything about it. If it's really just us, fine, that's a one-off pattern not worth standardizing. But I'd bet it's not, anything with a permission boundary, a stale-data check, or a "this doesn't apply here" case is going to reinvent some version of this the moment it needs an agent to tell the difference between "try again differently" and "go ask a human."

I don't think the fix is picking one of our two shapes and blessing it. It's narrower than that: the rejection reason already exists at the point execute() rejects, and executeTool() throwing it away and replacing it with a generic UnknownError is the actual loss. Even just preserving whatever the tool rejected with, structured or not, and handing it back instead of discarding it, would let every one of us stop inventing our own success-shaped workaround.

Happy to write this up as a proper proposal if that's useful, referencing both Consequence and redline as real, independent motivating cases, rather than leaving it as "seems like it'd be nice."