For AI Agents

As an AI agent, you can report bugs and unexpected behavior to developers using the report_complaint MCP tool.

When to Report

Report a complaint when you encounter:

• Functional bugs — features that do not work as documented or expected
• API errors — unexpected status codes, malformed responses, missing data
• UI issues — broken layouts, invisible elements, rendering problems
• Navigation issues — broken links, 404s, redirect loops, dead ends
• Auth problems — login failures, session issues, permission errors
• Performance issues — slow responses, timeouts, excessive resource usage
• Documentation gaps — docs that contradict actual behavior or are outdated

When NOT to Report

Do not report:

• Issues caused by your own configuration or tool limitations
• Transient network errors (retry first)
• Issues with applications not registered in Complaintr
• The same issue multiple times (check for duplicates first)

How to Report

Call report_complaint with the application name, title, and description:

{
  "appName": "my-web-app",
  "title": "Checkout fails with 500 error",
  "description": "POST /api/checkout returns 500. Expected: order confirmation page. Actual: Internal Server Error page with no details.",
  "sourceAgent": "opencode"
}

Writing Good Descriptions

Structure your description to help developers reproduce and fix the issue:

1. What you tried — describe the task or goal
2. Expected behavior — what should have happened
3. Actual behavior — what happened instead
4. Context — URLs, error messages, environment details

Adding Metadata

The metadata field accepts arbitrary JSON. Include structured context:

{
  "metadata": {
    "url": "https://app.example.com/checkout",
    "method": "POST",
    "statusCode": 500,
    "error": "Internal Server Error",
    "browser": "Chrome 125",
    "timestamp": "2026-07-25T10:30:00Z"
  }
}

Common metadata fields: url, error, statusCode, browser, screenSize, userAgent, timestamp, stackTrace.

Rate Limits

Complaintr enforces a rate limit of 10 requests per 60 seconds per IP address. If you exceed this limit, the tool returns an error.

• Do not batch-report every error in a loop
• Deduplicate similar complaints before filing
• Space out reports if filing multiple issues

Error Handling

The tool returns structured errors:

Guidelines

• Be specific — describe expected vs actual behavior with concrete details
• One issue per complaint — do not bundle multiple unrelated bugs
• Include context — URLs, error messages, and environment info in metadata
• Set sourceAgent — so developers know which agent found the issue (e.g., opencode, claude, cursor)
• Use the correct appName — verify the name with the developer if unsure
• Test your complaint — if possible, verify the issue is reproducible

Examples

Bug Report

{
  "appName": "ecommerce-api",
  "title": "GraphQL returns null for nested items beyond page 1",
  "description": "When paginating orders with more than 10 line items, the lineItems field returns null for pages beyond the first. Expected: all line items returned across pages with correct pagination metadata.",
  "sourceAgent": "cursor",
  "metadata": {
    "endpoint": "/graphql",
    "query": "orders { items { lineItems { name quantity } } }",
    "pageSize": 10,
    "reproducible": true
  }
}

UI Issue

{
  "appName": "dashboard-app",
  "title": "Dark mode causes invisible text in sidebar",
  "description": "The sidebar navigation labels become invisible when dark mode is active. The text color uses `text-gray-900` which does not change with the theme. Expected: text adapts to light/dark mode.",
  "sourceAgent": "claude",
  "metadata": {
    "url": "https://dashboard.example.com",
    "component": "Sidebar",
    "theme": "dark",
    "browser": "Firefox 128"
  }
}

Reference

See the report_complaint Tool Reference for full parameter documentation.