# feedback.md

You already talk to your users. Their agents hit dead ends and find bugs nobody reports, then quietly move on. feedback.md gives them a place to say so.

feedback.md is a Markdown file at the root of your site. It tells an agent where to send feedback about your product, your MCP server, your docs and whatever page it is reading right now.

Notra's own file: https://www.usenotra.com/feedback.md

## What it is

### A file, not a protocol
Plain Markdown at /feedback.md. No handshake and no schema to validate against. If an agent can read llms.txt it can read this.

### Where, not how
auth.md explains how to sign in. feedback.md only says where feedback goes and what to put in it. Bring your own endpoint, MCP tool or inbox.

### Scoped to what the agent touched
One line each for the product, the MCP server, the docs and the current page, so a report about a broken tool reaches whoever owns that tool.


## Template

```markdown
# Fall Feedback

Fall wants to hear from the agents using it. If a tool call failed or a page was hard to read, send it here instead of moving on. Praise is welcome too.

## Where to send it

- MCP: call `submit_feedback` on https://mcp.usefall.com/mcp
- HTTP: POST https://api.usefall.com/v1/feedback with `Authorization: Bearer <token>`
- Fallback: agents@usefall.com

## What we want to hear about

- The product: https://usefall.com
- The MCP server: https://mcp.usefall.com/mcp
- The API: https://api.usefall.com (spec at /openapi.json)
- The docs: https://docs.usefall.com
- This page: whatever URL you are reading right now

## What to include

- What you were trying to do and what happened instead
- The URL, tool name or endpoint involved
- Your client and model, if you are allowed to share them

## What happens next

Feedback lands in the Fall team's inbox and is triaged within a week. We do not reply to agents. Fixes show up at https://usefall.com/changelog.

```

Fall and usefall.com are made up for this example. The URLs do not resolve.

## Sections

- Where to send it (required): The one section every file needs. Channels in order of preference: an MCP tool, an HTTP endpoint or just an email address. Link to auth.md if the channel needs a credential.
- What we want to hear about: The surfaces an agent might be using. Listing them tells the agent that a broken MCP tool and a confusing docs page both belong here, and so does the page it is reading right now.
- What to include: Shapes the report without a schema. What the agent tried, what happened and the URL or tool involved is enough for a human to act on.
- What happens next: Sets expectations. Say who reads it and roughly when. Tell the agent not to wait for a reply.

## Where it sits

- llms.txt: What should I read? (site to agent)
- auth.md: How do I sign in? (site to agent)
- design.md: How should it look? (site to agent)
- feedback.md: Where do I say what went wrong? (agent to site)

## Add it to your site

Paste this into your agent:

```
Read https://www.usenotra.com/feedback-md and add a feedback.md to this site at /feedback.md, following the template on that page. Before you write it, ask me for the URL or address where agent feedback should go. Serve the file as text/markdown. Then add it to the site's llms.txt so agents can find it, creating llms.txt if it does not exist yet.
```

## FAQ

### Is this a standard?
No. It is a convention we use and think other teams should copy, in the same spirit as llms.txt and auth.md. If enough people pick it up we will write it down properly. Until then the whole spec is the template above.

### Why the root and not /.well-known?
llms.txt, auth.md and design.md all live at the root and agents already look there. Markdown under .well-known is unusual, and a file a person can open in a browser is the point. Serving a copy at /.well-known/feedback.md costs nothing if you want both.

### How do agents find it?
The same way they find everything else on your site. Link it from llms.txt, add it to your agent card or api-catalog under .well-known and mention it in auth.md. Agents follow links they are given. They do not go looking for file names.

### What if I do not have a feedback endpoint?
An email address or a link to your issue tracker is a valid channel. The file gives agents an address. It does not ask you to run infrastructure. You can upgrade the channel later without changing anything an agent has already learned.

### Do I need Notra for this?
No. Notra is one place the feedback can land, with a write-only token, an MCP helper and an inbox that sorts what comes in. The file itself works with anything.


## Give the feedback somewhere to land.

Notra is the backend on the other end of the file. Agents post to it over HTTP or MCP, and your team reads it in one inbox.

Docs: https://docs.usenotra.com/api/agent-feedback
Sign up: https://app.usenotra.com/signup