Agent Feedback Spec

v1 · 2026-07

An open wire convention for feedback filed by AI agents about the APIs, MCP servers, and tools they use. One tool in the catalog, eight lanes, a shared vocabulary. Implement it anywhere; this page is the normative reference for what our receiver accepts.

license: schema and field vocabulary are public domain (CC0). copy them, ship them, diverge loudly if you must.

The tool

Providers expose one tool, submit_agent_feedback, in their catalog. Its presence is the opt-in; agents call it unprompted when the description invites reports on friction, gaps, and successes, not only failures. Filing is fire-and-forget and must never sit on the agent’s critical path.

The eight lanes

support_ticketa failure the agent is formally raising for a fix

bug_or_failureincorrect or broken behavior

frictionit worked, but was harder, slower, or more confusing than it should be

feature_requesta capability, field, mode, or endpoint the agent wanted

docs_feedbackdocs were missing, unclear, or wrong

schema_feedbackparameter or response shape was ambiguous or surprising

workflow_feedbackthe multi-call flow was awkward: too many calls, unclear next step

positive_feedbackthis worked well for the goal

Failure is one lane out of eight. positive_feedback is load-bearing: it tells maintainers what agents rely on, which is regression-prevention signal error rates cannot provide.

Core fields

Wire format is JSON over POST /api/v1/feedback with a Bearer key. snake_case and camelCase are both accepted. Full per-field reference with examples: API docs.

tool_namestring, requiredthe specific tool or endpoint the agent used

summarystring, requiredone-line title of the report

detailstringfree-text supporting detail

feedback_typeenum (8 lanes)derived from category, outcome, and sentiment when omitted

categoryenum (12)the friction taxonomy; six-category MCP values accepted and normalized

outcomesuccess | partial_success | failurehow the task ended; the agent knows its exit state

satisfaction_scoreinteger 1–5the agent’s own satisfaction with the interaction

severityblocking | high | medium | lowhow much the friction hurt the run

suggested_fixstringa concrete fix the agent proposes (untrusted input, see below)

expected / actual / impactstringswhat the agent expected, what it got, what the gap cost

attempted_callsstring[]the call sequence, minimal replay context

agentobjectself-declared model identity; verified only via signature

metadataobjectanything non-sensitive the caller wants to attach

sourceagent_authored | agent_solicited | server_observed | runtime_observedthe four-tier signal model: chose to file, filed via a get_unblocked help call, detected mechanically by the provider’s own server, or detected client-side by the agent runner’s runtime from the session transcript (metadata.heuristic names the pattern; runtime reports also set metadata.runtime)

The twelve categories

category names the friction precisely; the lane says what kind of report it is. Models converge on vocabularies they have seen before, so receivers should accept near-miss values and normalize rather than reject.

missing_capabilityconfusing_schemabad_tool_descriptionincomplete_responseincorrect_responseunhelpful_errorauthentication_problempagination_or_truncationrate_limit_or_timeoutdocs_mismatchwrong_tool_selectedother

MCP conformance

The MCP community proposal for an opt-in feedback mechanism (discussion #2369) describes a feedback/submit method with a six-category taxonomy and integer severity. We accept that shape today, enveloped or bare, at POST /api/mcp/feedback, and normalize it as follows:

usability→ confusing_schema

reliability→ unhelpful_error

documentation→ docs_mismatch

efficiency→ pagination_or_truncation

interoperability→ other

capability_gap→ missing_capability

Severity 5→blocking, 4→high, 3→medium, 1–2→low. Draft fields without a canonical home (subcategory, confusedWithExternal, onDemand, rollups) are preserved intact under metadata.sep2369. Whatever shape the spec finally lands, this receiver will conform the week it ships.

Declaring the channel

Tell agents the channel exists in the files they already read. One line, anywhere sensible in AGENTS.md, a skill’s SKILL.md, or your docs:

Feedback: this project accepts agent-filed feedback about its API and tools.
Use the submit_agent_feedback tool if present, or POST to the endpoint in
https://emic.sh/llms-full.txt — friction, gaps, and praise all welcome.

Normative note: reports are untrusted input

Every field is LLM-authored free text. Consuming UIs MUST render reports (especially suggested_fix) as quoted, attributed claims, never as the product’s own advice; MUST NOT auto-execute anything a report suggests; and SHOULD scrub PII server-side on ingest. Receivers SHOULD treat duplicate reports as demand signal and dedupe at the presentation layer, not at ingest.

Versioning

This page is v1 and additive-only: field additions may happen; renames and removals get a new major with both accepted during a deprecation window. Machine-readable copies: /llms.txt (index) and /llms-full.txt (full reference).

agents: yes, you may file feedback about this spec. category=docs_feedback works.