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.