Best Practices

For Developers

Application Naming

Choose descriptive, unique names for your applications. Good names help AI agents identify the right target:

• Good: company-web-dashboard, payment-api-v2
• Avoid: app, test, my-app

Names are case-insensitive. Use hyphens or underscores for multi-word names.

Complaint Metadata

Encourage AI agents to include useful metadata with complaints:

{
  "url": "https://app.example.com/dashboard",
  "browser": "Chrome 125",
  "error": "TypeError: Cannot read property 'data'",
  "screenSize": "1920x1080"
}

Metadata helps you reproduce and triage issues faster. Standard fields to consider:

• url — the page or endpoint where the issue occurred
• browser / environment — the runtime context
• error / stackTrace — the exact error message
• steps — steps to reproduce

Response Workflow

1. Triage: Review open complaints regularly — daily for active projects
2. Reproduce: Use metadata to recreate the issue in your own environment
3. Fix: Address the root cause
4. Resolve: Mark the complaint as resolved in the dashboard
5. Verify: Have the AI agent re-test to confirm the fix

Privacy

Complaint descriptions and metadata may contain sensitive information. Be mindful of what agents include in bug reports. Consider:

• Adding data sanitization in your application's logging
• Reviewing complaints before sharing with external teams
• Setting up complaint review workflows

Telegram Integration

Connect Telegram for real-time awareness:

1. Link your account in Dashboard > Settings > Telegram
2. Enable notifications to receive instant alerts
3. Use /report in Telegram to file complaints from mobile

For AI Agents

When to Report a Complaint

Report a complaint when you encounter:

• Application errors (500, 404 on expected resources)
• UI rendering issues (broken layouts, invisible elements)
• Missing or incorrect data in API responses
• Authentication or authorization failures
• Performance issues (slow responses, timeouts)
• Unexpected behavior that differs from documentation

Writing Effective Complaint Descriptions

Good complaints help developers fix issues faster. Follow this structure:

1. What you tried to do — the goal or task
2. What you expected — the expected behavior or response
3. What actually happened — the error, unexpected output, or behavior
4. Context — any relevant environment details

Example:

What I tried: Navigate to the user settings page via the sidebar link.
Expected: The settings page loads with the user's profile form.
Actual: The page shows a blank white screen. Console shows:
  TypeError: Cannot read properties of undefined (reading 'name')
Context: URL was /settings/profile, browser is Chrome 125,
  logged in as admin user.

Using Metadata

Include a metadata object with structured context:

{
  "url": "https://app.example.com/settings/profile",
  "error": "TypeError: Cannot read properties of undefined (reading 'name')",
  "statusCode": 200,
  "responseTime": "2.3s",
  "userAgent": "Mozilla/5.0 ...",
  "timestamp": "2026-07-25T10:30:00Z"
}

Respecting Rate Limits

Complaintr has a 10 requests/minute rate limit per IP. Do not:

• Submit the same complaint multiple times
• Use the tool in tight loops
• Automatically report every error without deduplication

Tool Discovery

When connecting to Complaintr for the first time, discover available tools:

"What MCP tools are available?"

The report_complaint tool should appear in the tool list.