# Send agent feedback

`POST /api/v1/agent-feedback`

Tell the administrators of this instance about a problem with a tool. This is what the submit-feedback MCP tool calls. The person the agent works for never sees the report in Monica, only the call in their MCP history.

Send it at most once per task, and only when a tool got in the way. Paraphrase what the person asked, and use placeholders such as <contact> or <date> instead of names, dates and other details from the vault. Never include secrets.

## Body parameters

- `kind` (string, required): bug when a tool failed or returned something wrong, missing_tool when no tool could do it, unclear_description when a description misled you, improvement for a suggestion.
- `severity` (string, required): blocks_task when the task could not be finished, needs_workaround when it was finished another way, minor when it was finished with friction.
- `title` (string, required): One line naming the problem, up to 200 characters.
- `tool` (string, optional): The tool the report is about, or the name of the tool that is missing, up to 100 characters.
- `request` (string, optional): What the person asked, paraphrased, up to 4,000 characters.
- `steps` (array, optional): The tool calls tried, in order, at most 20. Each holds tool (required), arguments as a string, outcome (success or error, required) and result.
- `observed` (string, required): What happened, up to 4,000 characters. A placeholder such as test, todo or n/a answers 422.
- `expected` (string, required): What should have happened, up to 4,000 characters.
- `proposed_fix` (string, required): The fix you suggest, up to 4,000 characters.
- `proposed_code` (string, optional): Code for the fix, up to 8,000 characters.
- `model` (string, optional): The model the agent runs on, up to 100 characters.

## Returns

The id of the report and its status.

- `id` (uuid): The id of the report.
- `status` (string): Always new.

## Rate limit

Ten requests per minute, per user. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/agent-feedback \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "kind": "bug",
      "severity": "blocks_task",
      "title": "Yearly reminders on 29 February are refused",
      "tool": "create-contact-reminder",
      "steps": [
          {
              "tool": "create-contact-reminder",
              "arguments": "{\"contact\": \"<contact>\", \"day\": 29, \"month\": 2}",
              "outcome": "error",
              "result": "The date field must be a valid date."
          }
      ],
      "observed": "Any reminder on 29 February fails validation, with or without a year.",
      "expected": "The reminder is created and falls on 28 February in other years.",
      "proposed_fix": "Validate the day against a leap year when no year is given."
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/agent-feedback', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    kind: 'bug',
    severity: 'blocks_task',
    title: 'Yearly reminders on 29 February are refused',
    tool: 'create-contact-reminder',
    steps: [{"tool":"create-contact-reminder","arguments":"{\"contact\": \"<contact>\", \"day\": 29, \"month\": 2}","outcome":"error","result":"The date field must be a valid date."}],
    observed: 'Any reminder on 29 February fails validation, with or without a year.',
    expected: 'The reminder is created and falls on 28 February in other years.',
    proposed_fix: 'Validate the day against a leap year when no year is given.',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/agent-feedback', [
    'kind' => 'bug',
    'severity' => 'blocks_task',
    'title' => 'Yearly reminders on 29 February are refused',
    'tool' => 'create-contact-reminder',
    'steps' => [['tool' => 'create-contact-reminder', 'arguments' => '{"contact": "<contact>", "day": 29, "month": 2}', 'outcome' => 'error', 'result' => 'The date field must be a valid date.']],
    'observed' => 'Any reminder on 29 February fails validation, with or without a year.',
    'expected' => 'The reminder is created and falls on 28 February in other years.',
    'proposed_fix' => 'Validate the day against a leap year when no year is given.',
]);
```

## Response

`201`

```json
{
    "id": "3d9b7e21-6f4a-4c85-9a02-b81e5c47d613",
    "status": "new"
}
```
