Buckets funds into adaptation_only, mitigation_only, both, or neither.
    Returns count and metric total + share per bucket.
    

    Average number of approved projects per fund, grouped by fund_type.

    Use ONLY when the user explicitly wants an average per fund by type.

    Do NOT use for the TOTAL count of approved projects across all funds —
    use portfolio_summary (total_number_of_projects_approved).
    Do NOT use to find which individual funds approve the most projects —
    use rank_by_column on fund.csv with group_by='fund' and
    value_column='number_of_projects_approved'.

    source='fund' → uses pre-aggregated number_of_projects_approved per fund.
    source='projects' → distinct project_id per fund; filters_json narrows
    rows, e.g. '{"fund_type": "Multilateral"}'.

    agg: mean (default) | median | min | max
    

    Side-by-side comparison of multiple funds across selected metrics.
    'fund_ids': list of integer fund IDs.

    Always obtain IDs from search_funds (or resolve_entity + get_fund_details)
    for each user-supplied fund name in the same turn — do not guess or
    hard-code IDs like [1,2,3]; names and table order can change.

    'metrics': columns to include (default: all four stages + projects approved).
    

    Row count, column names, dtypes, and null counts for a dataset.
    Pass 'filename' (e.g. 'fund.csv') or 'dataset_uri' (e.g. 'cfu://funds').

    Use when column names are uncertain; skip as a first step if the system
    prompt or schema contract already lists the columns you need.
    

    Returns funds where a ratio metric falls below a threshold, sorted by
    ratio ascending (worst performers first).
    ratio_metric options: deposit_over_pledge, approval_over_deposit,
      disbursement_over_approval, disbursement_over_pledge.
    Use for screening underperformers, e.g. 'find funds with deposit/pledge < 0.5'.
    top_k: max funds to return (default 10, max 50). Check
      total_funds_below_threshold in the response to see if results were
      truncated — increase top_k if needed.
    Response columns: fund, ratio, pledge, disbursement only (trimmed to
      avoid context overflow).
    

    Write the full run log to runs/<run_id>.md and clear memory.
    Call once at the end of each user query to persist the audit trail.
    'extra_notes': optional free-text annotation to append to the log.
    

    For a single named fund: conversion ratios between each funding stage
    (deposit/pledge, approval/deposit, disbursement/approval,
    disbursement/pledge). Use when the user asks about the full funding
    pipeline for a specific fund, conversion ratios, how efficiently a fund
    moves money, or which fund has the highest/lowest disbursement-to-pledge
    ratio (call once per fund, or compare funds after resolving names).

    Do NOT use for portfolio-wide totals — use portfolio_summary.
    Do NOT use only to fetch raw stage amounts — use fund_stage_totals or
    fund_summary; use this tool when ratios / pipeline efficiency matter.

    Use search_funds first if the exact fund name is unknown.

    Response includes match_method (exact|fuzzy|unresolved), match_confidence
    (1.0 for exact), fuzzy_candidates with per-candidate similarity, and
    match_warning when fuzzy similarity is low — relay these to the user.
    

    Dollar gap between consecutive funding stages for one fund
    (fund_name set) or the whole portfolio (fund_name=None): pledge→deposit,
    deposit→approval, approval→disbursement.

    Use when the user asks how much pledged money has not been deposited,
    gaps between approved and disbursed for a specific fund, or stage gaps
    in the pipeline.

    Do NOT use for a global approved-vs-disbursed question with no fund
    named — use portfolio_summary for portfolio-wide totals and ratios.

    More direct than subtracting fund_stage_totals manually for gap questions.

    top_k: when fund_name is None (portfolio mode), return only the top N
      funds by deposit descending (default 20, max 30). Check total_funds
      and showing_top in the response to see if results were truncated.
    

    Raw dollar totals at each pipeline stage for a scope (no ratios).

    scope='portfolio' → all funds; scope='fund' → fund_id required;
    scope='fund_type' or 'sector' → filter by value (fund_type or
    fund_focus_sector on fund.csv).

    Use for total amounts by fund type or fund focus sector — not for
    conversion ratios; for a named fund's pipeline efficiency use
    fund_conversion_ratios or fund_summary.

    Do NOT use for portfolio-wide overview questions — use portfolio_summary
    first. Use search_funds / get_fund_details to resolve fund_id when needed.
    

    Structured profile card for one fund: metadata, all four stage metrics,
    portfolio share, and stage conversion ratios (deposit/pledge, etc.).
    Combines B's fund_summary with A's fund_conversion_ratios into one call.
    

    Totals and percentage share by fund_type, sorted descending.
    'metric' selects the stage column (pledge/deposit/approval/disbursement).
    'top_n' limits the number of fund types returned (default 20, max 200).
    

    Returns the compact audit trail for the current run:
    which tools were called, which dataset and columns each used.
    Call at any point mid-run to inspect what has been executed so far.
    

    Full dataset record for a single fund by fund_id.
    Use resolve_entity first if you only have a fund name, not an ID.
    

    Full schema contract as Markdown (stage discipline, integrity rules).

    Prefer get_schema_contract_summary for a compact JSON view. Not
    intended as the first step for routine lookups — use when you need the
    complete governance text or summary is insufficient.
    

    List registered datasets (URI, primary key, grain, description).

    Prefer analysis tools (portfolio_summary, rank_by_column, etc.) when
    the client already documents fund.csv / pledges.csv / projects.csv —
    do not call this as a first step only to rediscover known files, as
    responses can be large.

    Use when the dataset list is unknown or you need registry metadata.
    

    Sorted unique non-null values in a column (max 200).
    Use to discover valid filter values (fund_type names, sector names, etc.)
    before passing them to query tools.
    

    For any dataset table, groups rows by 'group_by' and reports missing-value
    counts across the specified 'columns'.
    Use before analysis to audit data completeness and find problematic records.
    Example: missing_report('fund.csv', 'fund_type', ['pledge', 'deposit'])
    (filename aliases map to database-backed tables by default.)
    

    Portfolio-wide totals across all funds: fund count, sums for each
    pipeline stage, total number_of_projects_approved when present, and
    adaptation/mitigation fund counts. No arguments.

    Use when the user asks: total pledged/approved/disbursed across ALL
    funds, how many projects approved in total, global share of approved
    funding disbursed (or not yet disbursed), or overall
    disbursement-to-pledge ratio (derive from returned totals).

    Do NOT use for a single fund — use fund_conversion_ratios,
    fund_summary, or fund_stage_totals(scope='fund', fund_id=...).
    

    First N rows of any dataset table (max 25).
    Pass 'filename' or 'dataset_uri'.
    Use to inspect raw data shape before analysis.
    

    Rank any grouping column by any numeric column in any dataset.

    When to use:
      - Top donors or contributors by pledged or deposited amount
        (pledges.csv, group_by contributor or country).
      - Regional or recipient analysis (projects.csv, group_by
        world_bank_region or country).
      - LDC vs non-LDC, SIDS, sector (e.g. agriculture), grant vs loan —
        group_by the relevant column on projects.csv.
      - Which funds approve the most projects (fund.csv,
        value_column=number_of_projects_approved).
      - Ascending or descending order (ascending parameter).

    Do NOT use when:
      - The dataset is long-format (stage as row values) and you rank by
        stage — use rank_entities instead.
      - On fund.csv you only need standard pipeline stage totals ranked —
        prefer rank_entities(filename='fund.csv', group_by='fund',
        stage=...) for pledge/deposit/approval/disbursement.

    'value_column': any numeric column in the file.
    'filters': optional {column: value | [value, ...]} dict to narrow rows
      before ranking. List values use OR logic (any match kept).
      If a string value does not match exactly, substring fallback is tried:
      unambiguous → auto-resolved with filter_resolutions in response;
      ambiguous → error listing candidates; no match → error listing
      available values for that column.
    'top_k': number of groups to return (default 20, max 100). Check
      total_groups_found in the response to see if results were truncated.
    

    Rank entities by a finance STAGE total: pledge, deposit, approval, or
    disbursement. Supported layouts: wide (one column per stage, e.g.
    fund.csv) or long ('stage' + 'amount' columns).

    When to use:
      - Ranking by a pipeline stage column (pledge/deposit/approval/
        disbursement), especially on fund.csv (e.g. top funds by pledged
        amount, most deposits received).

    Do NOT use when:
      - Ranking donors, contributors, countries, regions, or projects —
        use rank_by_column on pledges.csv or projects.csv with the right
        group_by and value_column.
      - Ranking by number_of_projects_approved, ratios, percentages, or
        non-stage numeric columns — use rank_by_column or
        fund_conversion_ratios / filter_funds_by_threshold as appropriate.
      - You need ascending sort — use rank_by_column.

    'stage': pledge | deposit | approval | disbursement.
    'filters': optional {column: value} dict to narrow rows before ranking.
    

    Fuzzy-match a user-supplied string against real column values (difflib).
    Always call this before any tool that takes a fund name, type, or sector
    string — prevents 'not found' errors from typos or partial names.
    Returns best_match (the value to pass to other tools) plus candidates.
    

    Keyword search across fund name, type, focus, and sector columns.
    Returns matching rows with key financial metrics.
    Each row includes match_relevance (0–1) vs the query for the best-matching
    searched cell — low scores mean substring-only hits; tell the user to verify.

    Use as the primary entry point when a user mentions a fund name or theme.
    

    Totals and share grouped by fund_focus_sector (adaptation / mitigation /
    multiple / none focus of the fund entity). 'metric' is the stage column
    (pledge/deposit/approval/disbursement).

    Use when the user asks how pledges or flows split across fund *focus*
    sectors at the fund level.

    Do NOT use for geographic regions — use rank_by_column on
    projects.csv grouped by world_bank_region (or country).
    Do NOT use for project-level sectors (e.g. agriculture) — use
    rank_by_column on projects.csv grouped by sector.
    

    Begin a new audit run for a user query.
    Call once at the start of each user question.
    Clears previous in-memory events and returns a run_id.
    All subsequent tool calls will log themselves to this run automatically.