Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#282 8 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
javascript
Domain
api

Research direction

Start by reading the WebMCP spec sections that define execute() results and tool errors, then review the seven-comment discussion for existing proposals or objections. Work out whether a structured refusal outcome fits the spec’s result model and how callers should distinguish it from success and schema-validation failure; done means the issue reaches a decided, specified behavior.

Written by the indexing model from the issue text.

Description

backwards-compatibility concerns enhancement

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.

Dominant language
Bikeshed
Stars
4.7k
Forks
328
Avg merge
1d 21h
Merged PRs (30d)
15

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from webmachinelearning/webmcp

All issues in webmachinelearning/webmcp

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.