| start_runA | 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.
|
| get_audit_trailA | 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.
|
| finalize_runA | 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.
|
| get_schema_contract_summaryA | Machine-readable JSON schema contract for all datasets (layers, keys,
grain, cross-layer rules). Use for cross-dataset analysis when you need formal governance rules.
Avoid as the first call for simple single-table questions when column
names are already provided to the model — the payload is large. |
| get_schema_contractA | 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_datasetsA | 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.
|
| describe_datasetA | 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.
|
| preview_datasetA | First N rows of any dataset table (max 25).
Pass 'filename' or 'dataset_uri'.
Use to inspect raw data shape before analysis.
|
| list_unique_valuesA | 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.
|
| resolve_entityA | 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.
|
| search_fundsA | 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.
|
| get_fund_detailsA | Full dataset record for a single fund by fund_id.
Use resolve_entity first if you only have a fund name, not an ID.
|
| fund_summaryA | 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.
|
| portfolio_summaryA | 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=...).
|
| sector_summaryA | 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.
|
| fund_type_distributionA | 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).
|
| adaptation_vs_mitigation_summaryC | Buckets funds into adaptation_only, mitigation_only, both, or neither.
Returns count and metric total + share per bucket.
|
| compare_fundsA | 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).
|
| fund_stage_totalsA | 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.
|
| fund_conversion_ratiosA | 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.
|
| rank_entitiesA | 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.
|
| rank_by_columnA | 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.
|
| filter_funds_by_thresholdA | 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).
|
| fund_stage_gapA | 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.
|
| avg_projects_per_fund_by_typeA | 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
|
| missing_reportA | 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.)
|
