allocate_portfolio

Suggest a donor portfolio: split budget_usd across top-ranked orgs (conviction_weighted / equal_split / top_only). Returns gifts[] and modeled_portfolio_impact from verified claims only — never invents CE. Always modeled≠guaranteed.

read-only

Argument	Type	Description
tax	string
risk	string
top_n	integer
method	string	Allocation method (alias: allocation_method on POST)
outcome*	string	lives_saved \| wellbeing_wellbys \| income
geography	string
red_lines	string	Comma-separated cause ids or tags to exclude
budget_usd*	number
include_funds	boolean

Input schema (JSON)

{
  "type": "object",
  "required": [
    "budget_usd",
    "outcome"
  ],
  "properties": {
    "tax": {
      "type": "string"
    },
    "risk": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string"
    },
    "top_n": {
      "type": "integer",
      "default": 4,
      "maximum": 20,
      "minimum": 1
    },
    "method": {
      "enum": [
        "conviction_weighted",
        "equal_split",
        "top_only"
      ],
      "type": "string",
      "description": "Allocation method (alias: allocation_method on POST)"
    },
    "outcome": {
      "type": "string",
      "examples": [
        "lives_saved",
        "wellbeing_wellbys",
        "income"
      ],
      "description": "lives_saved | wellbeing_wellbys | income"
    },
    "geography": {
      "type": "string"
    },
    "red_lines": {
      "type": "string",
      "description": "Comma-separated cause ids or tags to exclude"
    },
    "budget_usd": {
      "type": "number",
      "minimum": 0,
      "examples": [
        10000
      ]
    },
    "include_funds": {
      "type": "boolean",
      "default": true
    }
  },
  "additionalProperties": false
}

compare_charities

Side-by-side claims, recommendation tiers, and trust for two or more org_* ids. When the charities are measured in different outcome units (for example wellbeing in WELLBYs versus lives saved), units_differ.sentence says so in plain words; the units can't be converted without a moral judgment, which is the donor's. Answers carry decision_brief: the charity's own donate_url (next_action), the evaluator's fund as a let-the-evaluator-choose alternative, the like-for-like comparison page when one exists, and modeled: true / guaranteed: false when figures are present. No figure, rating or order is added.

read-only

Argument	Type	Description
ids*	string	Comma-separated org ids (minimum two)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "ids"
  ],
  "properties": {
    "ids": {
      "type": "string",
      "examples": [
        "org_against_malaria_foundation,org_malaria_consortium"
      ],
      "description": "Comma-separated org ids (minimum two)"
    }
  },
  "additionalProperties": false
}

create_giving_intent

NO-CHARGE deep-link giving handoff (Phase 3 MVP). Returns mode=deep_link, org donate_url, donation_proof=null, charge=false. Did It Work? never processes payment, stores cards, or calls Stripe. Optional modeled_impact is modeled≠guaranteed. Prefer GET; POST accepts the same fields as JSON body.

read-only

Argument	Type	Description
org_id*	string
vehicle	string
amount_usd*	number
include_impact	boolean	When true, attach modeled_impact (MODELED, NOT GUARANTEED)
values_profile_id	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "org_id",
    "amount_usd"
  ],
  "properties": {
    "org_id": {
      "type": "string",
      "pattern": "^org_[a-z0-9_]+$",
      "examples": [
        "org_against_malaria_foundation"
      ]
    },
    "vehicle": {
      "enum": [
        "direct_cash",
        "evaluator_fund",
        "daf",
        "stock_securities",
        "crypto",
        "payroll",
        "employer_match",
        "bequest",
        "time_volunteer",
        "skills_pro_bono",
        "network",
        "in_kind",
        "qcd_retirement",
        "other"
      ],
      "type": "string",
      "default": "direct_cash"
    },
    "amount_usd": {
      "type": "number",
      "examples": [
        100
      ],
      "exclusiveMinimum": 0
    },
    "include_impact": {
      "type": "boolean",
      "default": true,
      "description": "When true, attach modeled_impact (MODELED, NOT GUARANTEED)"
    },
    "values_profile_id": {
      "type": "string",
      "default": "vp_anonymous",
      "examples": [
        "vp_example_default"
      ]
    }
  },
  "additionalProperties": false
}

estimate_impact

Modeled expected outcomes from verified org claims scaled by gift_usd. Always modeled:true and guaranteed:false. Never invents CE; returns insufficient_data when no usable verified unit. Answers carry decision_brief: the charity's own donate_url (next_action), the evaluator's fund as a let-the-evaluator-choose alternative, the like-for-like comparison page when one exists, and modeled: true / guaranteed: false when figures are present. No figure, rating or order is added.

read-only

Argument	Type	Description
org_id*	string
gift_usd*	number

Input schema (JSON)

{
  "type": "object",
  "required": [
    "org_id",
    "gift_usd"
  ],
  "properties": {
    "org_id": {
      "type": "string",
      "examples": [
        "org_against_malaria_foundation"
      ]
    },
    "gift_usd": {
      "type": "number",
      "examples": [
        1000
      ],
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

get_claim

Fetch one claim row by claim_id from data/claims_index.json (e.g. eval_gw_amf__0). Index-only — never invents values. Prefer list_claims with filters when browsing. Wave BI provenance on the response. Org narrative fields remain untrusted (ADR 0008).

read-only

Argument	Type	Description
id*	string	claim_id (path {id}), e.g. eval_gw_amf__0

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$",
      "examples": [
        "eval_gw_amf__0"
      ],
      "description": "claim_id (path {id}), e.g. eval_gw_amf__0"
    }
  },
  "additionalProperties": false
}

get_ledger_record

Fetch one outcome-ledger record by record_id (e.g. ldg_eval_gw_amf__0) plus any follow-up results. Read-only; 404 for unknown ids; modeled, not guaranteed. Read-only API, live at https://api.diditwork.org.

read-only

Argument	Type	Description
id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^ldg_[a-z0-9_]+$",
      "examples": [
        "ldg_eval_gw_amf__0"
      ]
    }
  },
  "additionalProperties": false
}

get_meta

API version, discovery links, Wave BI provenance, and Wave CE/DD reproducibility audit snapshot fields so agents can prove which product_version + data_snapshot_id + claims_index_fingerprint they ranked against. Includes mixes_units_in_ranking:false, adr_0007_status (from moral_weights_policy.json — Proposed until Ho Hum Accept; never invent Accepted), claims_index_fingerprint (short sha256 of data/claims_index.json), and counts {orgs, interventions, causes, sources_files}. Focused twin: GET /v1/meta/snapshot (same audit_snapshot object). Never invents CE.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_org

Fetch one organization / program / fund record by stable org_* id. Answers carry decision_brief: the charity's own donate_url (next_action), the evaluator's fund as a let-the-evaluator-choose alternative, the like-for-like comparison page when one exists, and modeled: true / guaranteed: false when figures are present. No figure, rating or order is added.

read-only

Argument	Type	Description
id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^org_[a-z0-9_]+$",
      "examples": [
        "org_against_malaria_foundation"
      ]
    }
  },
  "additionalProperties": false
}

get_review_queue

Human exception-review queue (read-only). Returns items from data/review/queue.json for Ho Hum (sole human operator). Default status=open; pass status=all for history. Approve/reject is offline file edit only — write_api is always false; there is no unauthenticated write/approve API. Agents must never auto-clear trust flags or invent CE/EINs/donate URLs to close tickets.

read-only

Argument	Type	Description
status	string	Filter by item status (default open on the server)

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "status": {
      "enum": [
        "open",
        "approved",
        "rejected",
        "all"
      ],
      "type": "string",
      "examples": [
        "open",
        "all"
      ],
      "description": "Filter by item status (default open on the server)"
    }
  },
  "additionalProperties": false
}

get_tax

Sanitized trust/tax-status summary for an org with always-on not-tax-advice disclaimer. Prefer before asserting US deductibility. deductibility.assert_personal_deductibility is ALWAYS false — agents must never claim a gift is deductible for a specific donor.

read-only

Argument	Type	Description
org_id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "org_id"
  ],
  "properties": {
    "org_id": {
      "type": "string",
      "pattern": "^org_[a-z0-9_]+$",
      "examples": [
        "org_against_malaria_foundation"
      ]
    }
  },
  "additionalProperties": false
}

get_trust

Trust and safety flags for an org. REQUIRED before asserting US tax deductibility or registry status.

read-only

Argument	Type	Description
org_id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "org_id"
  ],
  "properties": {
    "org_id": {
      "type": "string",
      "pattern": "^org_[a-z0-9_]+$",
      "examples": [
        "org_against_malaria_foundation"
      ]
    }
  },
  "additionalProperties": false
}

get_values_profile

Fetch one values-profile preset by id (vp_*). Use after list_values_profiles or when the donor picked a named preset. Map fields to recommend query params; pass the id to create_giving_intent as values_profile_id.

read-only

Argument	Type	Description
id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^vp_[a-z0-9_]+$",
      "examples": [
        "vp_lives_saved_max",
        "vp_wellbeing_tilt",
        "vp_us_501c3_preferred",
        "vp_non_cash_interest",
        "vp_income_benchmark"
      ]
    }
  },
  "additionalProperties": false
}

list_charities

The Did it work? charity list, filtered: the charities https://diditwork.org/charities/ shows for cause, evaluator (by), measure, follow-up and a word search, in the page's own order. Hide-only: filters never re-order, score or rank, and there are no figures here (each row links to its claims file and API record). Same JSON as https://diditwork.org/charities/index.json for the same filter. Unknown, empty or misspelled values return isError with invalid_filter, the allowed values and a cleaned address, never a guess. Call with no arguments to get the full list and every allowed value with its count. Read-only API, live at https://api.diditwork.org. When count is 0 the answer carries coverage: what we don't cover (for example climate, or a charity the evaluators we follow don't rate) and what to do instead; never a guessed rating. When the words name a well-known charity that is not on our list, or a cause or topic we don't rate, a non-empty answer carries partial_coverage saying so.

read-only

Argument	Type	Description
q	string	Words that must all appear in the name, description, designation, cause names or everyday words for those causes; case and accents ignored. No leading or trailing spaces.
by	string	An evaluator slug (parameters.by).
cause	string	A cause slug; call with no arguments to see parameters.cause with counts.
measure	string	What the evaluator's figures measure (parameters.measure).
followup	boolean	true: only charities with a follow-up record in the outcome ledger.

list_claims

Read-only flat claims index (data/claims_index.json). Optional filters: org_id, evaluation_id, verified. Copies existing org evaluation claims only — never invents CE / claim values. Prefer verified:true + non-null value when quoting cost-effectiveness. Wave BI provenance on the response. Org narrative fields remain untrusted (ADR 0008). Answers carry decision_brief: the charity's own donate_url (next_action), the evaluator's fund as a let-the-evaluator-choose alternative, the like-for-like comparison page when one exists, and modeled: true / guaranteed: false when figures are present. No figure, rating or order is added.

read-only

Argument	Type	Description
org_id	string	Filter to one org_* id
verified	string	If true/false, filter on claim.verified (string query as HTTP API)
evaluation_id	string	Filter to one evaluation_* id

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "pattern": "^org_[a-z0-9_]+$",
      "examples": [
        "org_against_malaria_foundation"
      ],
      "description": "Filter to one org_* id"
    },
    "verified": {
      "type": "string",
      "examples": [
        "true",
        "false"
      ],
      "description": "If true/false, filter on claim.verified (string query as HTTP API)"
    },
    "evaluation_id": {
      "type": "string",
      "examples": [
        "eval_gw_amf"
      ],
      "description": "Filter to one evaluation_* id"
    }
  },
  "additionalProperties": false
}

list_leaderboards

Per-outcome-family leaderboards from data/ranking/leaderboards.json. Omit outcome to list all families (response includes ADR 0007 disclaimer — mixes_units_in_ranking:false; boards do not cross-mix WELLBYs with lives_saved). Pass outcome= to fetch one family's frozen ranked board. Never invents cross-unit moral weights.

read-only

Argument	Type	Description
outcome	string	lives_saved \| wellbeing_wellbys \| income (aliases accepted). Omit for all families.
outcome_preference	string	Alias for outcome (values-profile field name)

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "outcome": {
      "type": "string",
      "examples": [
        "lives_saved",
        "wellbeing_wellbys",
        "income"
      ],
      "description": "lives_saved | wellbeing_wellbys | income (aliases accepted). Omit for all families."
    },
    "outcome_preference": {
      "type": "string",
      "description": "Alias for outcome (values-profile field name)"
    }
  },
  "additionalProperties": false
}

list_ledger_records

List outcome-ledger ("Did it work?") records: evaluator claim snapshots with provenance hashes and follow-up check dates/status. Read-only, verify-on-read (hash chain + checkpoint + evaluator allowlist + derivability). Read-only API, live at https://api.diditwork.org.

read-only

Argument	Type	Description
org_id	string
status	string
evaluator	string
record_kind	string
intervention_id	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "pattern": "^[a-z0-9_]{1,96}$",
      "examples": [
        "org_against_malaria_foundation"
      ]
    },
    "status": {
      "enum": [
        "pending",
        "confirmed",
        "contradicted",
        "unverifiable"
      ],
      "type": "string"
    },
    "evaluator": {
      "enum": [
        "givewell",
        "hli",
        "ace",
        "who",
        "ihme"
      ],
      "type": "string"
    },
    "record_kind": {
      "enum": [
        "claim_snapshot",
        "follow_up_result"
      ],
      "type": "string"
    },
    "intervention_id": {
      "type": "string",
      "pattern": "^[a-z0-9_]{1,96}$",
      "examples": [
        "int_itn"
      ]
    }
  },
  "additionalProperties": false
}

list_values_profiles

List static values-profile presets (same catalog as the demo). Load before recommend when the donor stated preferences. Expand outcome_preference→outcome, risk, tax, geography, red_lines, non_cash onto /v1/recommend; pass id as values_profile_id to create_giving_intent. Read-only; never mutates ranking CE.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

recommend_charity

Conviction-ranked orgs for one outcome family. Pass values_profile_id (preferred) and/or outcome. Returns values_filtering + exclusions[] with why-filtered reasons (never silent red-line drops). Does not mix units (ADR 0007 Proposed). Never invents CE. An unknown outcome (for example climate) or an empty result carries coverage: what we don't rate and what to do instead; never a guessed rating.

read-only

Argument	Type	Description
tax	string
risk	string
limit	integer
outcome	string	lives_saved \| wellbeing_wellbys \| income (aliases accepted)
non_cash	boolean	Prefer orgs with non_cash_giving options
geography	string
red_lines	string	Comma-separated cause ids or tags to exclude
budget_usd	number
require_geography	boolean

search_orgs

Heuristic search by cause, outcome family, or donor intent phrase. Prefer recommend_charity when the user wants ranked 'best for outcome' results. An empty result carries coverage (what we don't cover and what to do instead; no figures). A non-empty result that answers only part of the question carries partial_coverage: which part is covered, which is not (for example animal welfare, humanitarian relief, scam checks or tax-return data) and who does assess the rest.

read-only

Argument	Type	Description
cause	string
intent	string
outcome	string	lives_saved \| wellbeing_wellbys \| health_dalys \| income

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "cause": {
      "type": "string",
      "examples": [
        "malaria"
      ]
    },
    "intent": {
      "type": "string",
      "examples": [
        "best charity to save lives"
      ]
    },
    "outcome": {
      "type": "string",
      "description": "lives_saved | wellbeing_wellbys | health_dalys | income"
    }
  },
  "additionalProperties": false
}

Did It Work?

Try it

allocate_portfolio Read-only

Did It Work?

Try it

allocate_portfolio Read-only

Tools (19)