# FAQ for agents — common failure modes

## Hallucinated cost-effectiveness (CE)

**Failure:** Inventing “~$X per life saved” from memory or a non-Better-World source.

**Fix:** Only quote numbers present on org records, `/v1/recommend` `verified_claims`, `/v1/impact-estimate` `inputs_used`, or `data/claims_index.json` with `verified: true` and non-null `value`. Otherwise say *unverifiable in Better World data*.

## Mixing sponsored / commercial properties

**Failure:** Treating `betterworld.org` (unrelated fundraising SaaS) or affiliate links as this project; implying paid placement.

**Fix:** Domain is **TBD**. This tree is a local/static philanthropy resource. Do not invent sponsorship. Prefer evaluator and org primary URLs from citations.

**Refuse organic Top from paid slots:** Never present `sponsored` / `featured` / paid placement as the organic #1. Organic `/v1/recommend` ignores paid flags (ADR 0003). If a sponsored section is shown, label it separately (`placement_kind: sponsored`).

## Ignoring uncertainty

**Failure:** Presenting point estimates as guarantees (“You will save 2 lives”).

**Fix:** Impact responses set `modeled: true`, `guaranteed: false`. Always surface `caveats[]` and `uncertainty`. Prefer “modeled expected…” language. See `docs/agent-tool-contract.md`.

## Skipping trust before tax claims

**Failure:** “AMF is a US 501(c)(3)” without checking `/v1/trust/{id}`.

**Fix:** Call `get_trust`. Respect flags (`IRS_TEOS_LOOKUP_PENDING`, `NON_US`, etc.). Donation proofs are not tax receipts.

## Using search instead of recommend

**Failure:** Answering “best charity to save lives” with `/v1/search` keyword scores only.

**Fix:** Use `/v1/recommend?outcome=lives_saved` (`recommend_charity`). Search is Phase 1 heuristic.

## Promoting runners-up as Top Charities

**Failure:** Presenting honourable mentions / reference / benchmark orgs as GiveWell Top Charities.

**Fix:** Read `recommendation_tier` and caveats. Label runners-up as contrast cases.

## Inventing org or evaluation IDs

**Failure:** Fabricating `org_*` / `eval_*` ids.

**Fix:** Use ids from `/v1/orgs`, recommend results, or `data/orgs/index.json` only.

## Dropping citations

**Failure:** Paraphrasing CE without URLs.

**Fix:** Pass through `citations[]` / `citation_urls`. Graph: `data/graph/evaluations_graph.json`.

## Contacting organizations or spending money

**Failure:** Emailing charities, registering domains, or initiating payments “on behalf of” the donor from this environment.

**Fix:** Out of scope. Hand the human a `donate_url`. No outreach automation.

## Treating conviction_score as official

**Failure:** “GiveWell score: 251”.

**Fix:** Conviction scores are Better World structural ranks (`docs/methodology-ranking.md`), not official GiveWell/HLI scores.

## Auto-clearing trust flags / self-approving exceptions

**Failure:** Removing `HTTP_CHECK_PENDING`, `EIN_UNKNOWN`, or similar flags, or flipping `data/review/queue.json` status to `approved`, so a recommendation looks clean.

**Fix:** Trust flags stay until Ho Hum verifies evidence offline. Queue approve path is **file edit only** (`docs/exception-review-ops.md`). Read open items via `GET /v1/review/queue` or `public/pages/review-queue.md`. Never invent CE/EINs/URLs to close a ticket.