report_complaint Tool

The report_complaint tool submits structured bug reports to Complaintr from AI agents.

Parameters

Parameter	Type	Required	Max Length	Description
`appName`	string	Yes	100	The name of the application that has the issue
`title`	string	Yes	200	A brief, descriptive title summarizing the issue
`description`	string	Yes	5000	Detailed description including expected vs actual behavior
`sourceAgent`	string	No	50	Name of the AI agent (e.g., `opencode`, `claude`, `cursor`)
`metadata`	object	No	—	Additional structured context (URLs, errors, environment info)

appName

The application name must match a registered application exactly (case-insensitive). The developer registers this in the Complaintr dashboard.

Best practice: Ask the developer what name they registered, or check recent context for the correct application name.

title

A concise summary that helps the developer quickly understand the issue. Keep it under one sentence.

Good: "Login button returns 500 on Safari" Avoid: "There's a problem with the login page when I click the button and it doesn't work"

description

The most important field. Structure it to include:

What you tried to do
What you expected to happen
What actually happened
Any error messages or unexpected output

sourceAgent

Identify yourself so the developer knows which agent encountered the issue. Common values: opencode, claude, chatgpt, cursor, windsurf, copilot.

metadata

Optional structured data in JSON format. Useful fields:

Field	Type	Description
`url`	string	The URL or endpoint where the issue occurred
`error`	string	The exact error message or code
`statusCode`	number	HTTP status code if applicable
`browser`	string	Browser name and version
`screenSize`	string	Viewport dimensions
`stackTrace`	string	Full stack trace if available
`requestBody`	object	The request payload that triggered the error
`responseBody`	object	The unexpected response
`reproducible`	boolean	Whether the issue can be reproduced consistently
`timestamp`	string	ISO 8601 timestamp of when the issue occurred

Returns

Success (201)

{
  "id": "comp_abc123",
  "title": "Login page redirects to 404",
  "application": "my-web-app",
  "createdAt": "2026-07-25T10:35:00.000Z"
}

id — unique complaint identifier (use for reference)
application — the resolved application name
createdAt — server timestamp of submission

Errors

HTTP Status	Message	Cause
400	`"appName, title, and description are required"`	Missing required fields
400	`"appName must be a string with at most 100 characters"`	Field exceeds max length
400	`"title must be a string with at most 200 characters"`	Field exceeds max length
400	`"description must be a string with at most 5000 characters"`	Field exceeds max length
404	`"Application not found"`	The appName does not match any registered application
429	`"Too many requests. Please try again later."`	Rate limit exceeded (10 per 60s per IP)
500	`"Internal server error: ..."`	Unexpected server error

Example Calls

Minimal Report

{
  "appName": "ecommerce-api",
  "title": "GraphQL returns null for nested items beyond page 1",
  "description": "When paginating orders, lineItems returns null for orders with more than 10 items. Expected: all lineItems returned with pagination."
}

Full Report with Metadata

{
  "appName": "saas-dashboard",
  "title": "CSV export includes deleted users",
  "description": "The user export feature at /admin/users/export includes soft-deleted users in the CSV output. The UI does not show these users. Expected: only active users in the export.",
  "sourceAgent": "opencode",
  "metadata": {
    "url": "https://dashboard.example.com/admin/users/export",
    "endpoint": "GET /api/admin/users/export",
    "format": "csv",
    "issue": "Soft-deleted users (deleted_at IS NOT NULL) are included",
    "reproducible": true,
    "timestamp": "2026-07-25T10:30:00Z"
  }
}

Report from Claude Desktop

{
  "appName": "payment-gateway",
  "title": "Webhook signature verification fails on retries",
  "description": "The Stripe webhook endpoint at /api/webhooks/stripe returns 400 on retry attempts because the signature uses the original timestamp. Expected: retries should be handled gracefully with idempotency keys.",
  "sourceAgent": "claude",
  "metadata": {
    "endpoint": "POST /api/webhooks/stripe",
    "statusCode": 400,
    "provider": "Stripe",
    "error": "Signature verification failed: timestamp outside tolerance"
  }
}

Constraints

Constraint	Value
Rate limit	10 requests per 60 seconds per IP
`appName` matching	Case-insensitive
Max `appName` length	100 characters
Max `title` length	200 characters
Max `description` length	5000 characters
Max `sourceAgent` length	50 characters

Discovery

When connecting to a Complaintr MCP server, tools are auto-discovered. Ask your host environment:

"What MCP tools are available?"

The report_complaint tool should appear in the listing. No manual registration is needed.

report_complaint Tool

On this page