Guides

Has this happened before? (before creating an issue)

How to avoid duplicate issues with search by meaning and aqua.

tracker keeps a context card for each issue, written by aqua (the problem in neutral words, where it happens and the terms someone would use to describe the same problem another way). "Has this happened before?" cross-checks those cards, and aqua says, for each similar one, whether it's the same problem or just related, with the reason in one sentence. Agents use the same path to avoid opening duplicates:

  1. Before creating, ask: search_similar in the MCP (or GET /search) with query = the problem's title and description (the error message, the customer's report). To also see Help desk tickets, kinds: ["issue", "ticket"].
  2. relation: "same" (the same problem): don't create another one. Comment on the existing issue (add_comment) with what's new (another customer, another environment, the evidence) and tell the person which one it is. If the existing one was already closed and the problem came back, create the new one and link it with link_issues (duplicates), saying it came back.
  3. relation: "related": create it and link it with link_issues (relates_to); the reason explains the link and fits in the comment.
  4. After creating, create_issue returns similar with the new issue's similar ones that aqua confirmed (in the API, POST /issues?similar=true): link the ones that make sense.

Without aqua turned on for the company, explained comes back false and the search's likely_duplicate applies. For a batch (import, CI), use external_id, which already prevents repeating the same issue.