← All Test Cases

ENT-001

entity disambiguation

critical

Repetitions

Documents

Questions

Reasoning

DIRECT

entity-disambiguation same-name different-entity

📖 In Plain English

What this category tests

Does the brain correctly distinguish entities with similar names?

How the test works

Documents describe different entities sharing a common word (e.g. Widget Pro / Widget Max / Widget Lite). The test asks about one specific entity and checks the others aren't returned by mistake.

Why it matters

Many domains have similar-named entities — confusing them produces wrong answers.

⚙️ How a single rep runs

① Generate

Model creates 2 synthetic documents and 1 question with unique canary tokens

→ Fresh content per run prevents memorization and proves real retrieval

② Ingest (MCP)

Model calls brain_ingest to store the 2 documents

→ Tests the brain's storage and indexing pipeline

③ Query (MCP)

Model answers the question using brain retrieval tools (search, fetch, context_pack, etc.)

→ Core test — does the brain return correct evidence and let the model build a faithful answer?

④ Evaluate

Model judges the answer against ground truth (the document it generated in phase 1)

→ Produces a score 0–100 with detailed sub-scores (retrieval, fidelity, reasoning, etc.)

This rep is run 3 times per test run. A pass requires score ≥ 85 and no critical failures.

🔬 Technical Instructions (raw prompts sent to AI)

🔧 ① Setup Instructions 1466 chars

Generate two documents about two DIFFERENT entities that share the same first name.
Ask a question that only applies to one of them — the answer must identify the correct one.

Requirements:
- Doc A: "<FirstName> <LastName-A> is the <Role-A> at <Company-A>." (fictional)
- Doc B: "<FirstName> <LastName-B> is the <Role-B> at <Company-B>." (same FirstName, different LastName/Role/Company)
- Question: "What role does <FirstName> <LastName-A> hold?" — includes the full name to disambiguate.
- source_ids: KB-{{RUN}}-ENT-001-A-v1 and KB-{{RUN}}-ENT-001-B-v1.

Output ONLY this JSON:
{
  "run_id": "{{RUN}}",
  "test_id": "ENT-001",
  "repetition": {{REP}},
  "documents": [
    {"source_id": "KB-{{RUN}}-ENT-001-A-v1", "content": "<FirstName> <LastName-A> is the <Role-A> at <Company-A>.", "title": "<title>", "version": 1},
    {"source_id": "KB-{{RUN}}-ENT-001-B-v1", "content": "<FirstName> <LastName-B> is the <Role-B> at <Company-B>.", "title": "<title>", "version": 1}
  ],
  "questions": ["What role does <FirstName> <LastName-A> hold?"],
  "expected_answers": [{
    "question_index": 0,
    "correct_answer": "<Role-A>",
    "required_source_ids": ["KB-{{RUN}}-ENT-001-A-v1"],
    "required_quote": "<exact Doc A sentence>",
    "required_label": "DIRECT",
    "must_refuse": false,
    "notes": "Two people share a first name. Full name in question disambiguates. Must return Role-A from Doc A only. Returning Role-B or Doc B is a critical failure."
  }]
}

▶ ② Execution Instructions 144 chars

Use ONLY MCP Knowledge Brain retrieval tools with domain="brain-test".
Question: {{QUESTION}}
Return ONLY this JSON:
{{REQUIRED_ANSWER_SCHEMA}}

⚖ ③ Judge Instructions 342 chars

Ground truth:
{{SETUP_CONTEXT_JSON}}

Tested AI answer:
{{EXEC_ANSWER_JSON}}

Two entities share a first name. The question uses the full name to disambiguate. Must return from Doc A only.
Critical failures: returned Role-B (wrong person), cited Doc B, cited both docs, hallucinated source_id.

Return ONLY this JSON:
{{JUDGE_RESULT_SCHEMA}}

Critical Failure Conditions

returned_wrong_persons_role
cited_wrong_document
hallucinated_source_id

Recent Run History

3 runs

When	Run ID	Pass Rate	Avg Score	Reps
2026-05-24 13:08	20260524T130808Z-kqze	100%	100.0	1/1	View →
2026-05-24 12:41	20260524T124148Z-z2do	0%	0	0/1	View →
2026-05-24 11:37	20260524T113756Z-kduj	100%	100.0	1/1	View →

📄 Raw YAML cases/entity_disambiguation/ENT-001.yaml

schema_version: "1.0"
test_id: "ENT-001"
category: "entity_disambiguation"
severity: "critical"
repetitions: 3
reasoning_type: "DIRECT"
num_documents: 2
num_questions: 1
tags: ["entity-disambiguation", "same-name", "different-entity"]

setup_instructions: |
  Generate two documents about two DIFFERENT entities that share the same first name.
  Ask a question that only applies to one of them — the answer must identify the correct one.

  Requirements:
  - Doc A: "<FirstName> <LastName-A> is the <Role-A> at <Company-A>." (fictional)
  - Doc B: "<FirstName> <LastName-B> is the <Role-B> at <Company-B>." (same FirstName, different LastName/Role/Company)
  - Question: "What role does <FirstName> <LastName-A> hold?" — includes the full name to disambiguate.
  - source_ids: KB-{{RUN}}-ENT-001-A-v1 and KB-{{RUN}}-ENT-001-B-v1.

  Output ONLY this JSON:
  {
    "run_id": "{{RUN}}",
    "test_id": "ENT-001",
    "repetition": {{REP}},
    "documents": [
      {"source_id": "KB-{{RUN}}-ENT-001-A-v1", "content": "<FirstName> <LastName-A> is the <Role-A> at <Company-A>.", "title": "<title>", "version": 1},
      {"source_id": "KB-{{RUN}}-ENT-001-B-v1", "content": "<FirstName> <LastName-B> is the <Role-B> at <Company-B>.", "title": "<title>", "version": 1}
    ],
    "questions": ["What role does <FirstName> <LastName-A> hold?"],
    "expected_answers": [{
      "question_index": 0,
      "correct_answer": "<Role-A>",
      "required_source_ids": ["KB-{{RUN}}-ENT-001-A-v1"],
      "required_quote": "<exact Doc A sentence>",
      "required_label": "DIRECT",
      "must_refuse": false,
      "notes": "Two people share a first name. Full name in question disambiguates. Must return Role-A from Doc A only. Returning Role-B or Doc B is a critical failure."
    }]
  }

execution_instructions: |
  Use ONLY MCP Knowledge Brain retrieval tools with domain="brain-test".
  Question: {{QUESTION}}
  Return ONLY this JSON:
  {{REQUIRED_ANSWER_SCHEMA}}

judge_instructions: |
  Ground truth:
  {{SETUP_CONTEXT_JSON}}

  Tested AI answer:
  {{EXEC_ANSWER_JSON}}

  Two entities share a first name. The question uses the full name to disambiguate. Must return from Doc A only.
  Critical failures: returned Role-B (wrong person), cited Doc B, cited both docs, hallucinated source_id.

  Return ONLY this JSON:
  {{JUDGE_RESULT_SCHEMA}}

critical_failures:
  - "returned_wrong_persons_role"
  - "cited_wrong_document"
  - "hallucinated_source_id"