Find the smallest relevant signed source, columns, and join paths for a question.

Use the returned source field verbatim in benthic_query. If join_paths is empty, make separate
benthic_query calls; never invent a join.

One call is normally enough: it returns the best relations together with their columns, and
columns_truncated says when that list is partial. Ask again for more columns only when
columns_truncated is true, by passing detail='full'. A wrong column guess is recoverable rather
than fatal, because benthic_query reports the near-miss signed name.

Core access rules:

• Call benthic_discover before benthic_query, and pass its source value verbatim.

• Use benthic_join only for a signed path returned by discovery; never invent a join.

• Partial joins require context_conditions and must be reported as provisional.

• Heuristic matches are not exact; keep the returned reliability warning in the answer.

• Never derive totals from truncated or incomplete source data.

• Call benthic_playbook(dataset) when a question needs domain conventions for that dataset.

• Dates in this catalog are ISO-8601; filter with gte/lte rather than string comparison.

• Never use a current-only view to answer a historical question.

• You have a limited number of turns, so once you have the rows you need you must stop calling tools and write the final answer, because a question left unanswered scores zero even when every call succeeded.

• usaspending: Federal award transactions and the recipient entity index.

• irs_ng: IRS exempt organization records, including Form 990 details.

• samer: SAM entity registrations, the bridge between USAspending and IRS identifiers.

• up_cdmaps: Congressional district boundaries, queried through spatial RPCs.

• usp_cl: Congressional legislators and executive terms, including historical terms.

Dataset-specific access conventions built from signed metadata and prior sessions.

Call once per dataset before answering a question that depends on domain conventions: which
source to use, which columns are authoritative, which mistakes to avoid, and which signed join
paths and RPC operations exist. Join recipes come from the signed catalog and are never
invented here. Omit dataset for a routing index of every dataset.

To move data between two relations, pass from_relation and to_relation as 'dataset.relation'
instead of a dataset. That returns the signed route hop by hop, shortest first, with the exact
arguments for each benthic_join call, and nothing else. Do this rather than searching
benthic_discover for a join path: a search can be rephrased, so a request for a path that does
not exist comes back looking like a request that was worded wrongly.

Run one bounded read-only relation query.

Call benthic_discover first and pass its source value verbatim. where uses column=operator.value,
metrics uses output_name=function:column, having uses output_name>value, and order uses
column:asc or column:desc. The name in a metric is the output column, not the source column.
Operators: eq, neq, gt, gte, lt, lte, like, ilike, in, is.null, not.is.null. Aggregates are complete
or rejected; never infer totals from a truncated source.

Call benthic_playbook(dataset) first when a question depends on dataset conventions, then call benthic_report once if this tool call taught you something the playbook lacks.

Run one signed join using qualified sources.

Omit left_column and right_column when exactly one reliable identifier path connects the two
sources, and the signed path is resolved for you. That is the common case and it saves having to
look the path up first. Columns are still required whenever the path is ambiguous, absent, or
anything other than a reliable identifier join, so a heuristic or partial join is never chosen
for you; the error lists the candidates instead.

The adapter follows signed reliability metadata and returns warnings. Partial joins require
context_conditions. The left key filter is propagated to the right source; do not invent columns
or unsigned relationships.

Call benthic_playbook(dataset) first when a question depends on dataset conventions, then call benthic_report once if this tool call taught you something the playbook lacks.

Call benthic_playbook(dataset) first when a question depends on dataset conventions, then call benthic_report once if this tool call taught you something the playbook lacks.

Record one mistake you made and the correction, so future sessions do not repeat it.

Call this once after answering, only if a tool call or a source convention misled you. Write the lesson as an instruction to your future self ("use X instead of Y"), not as a complaint. Reports are stored as pending and are only served to later sessions after catalog verification and an offline A/B evaluation, so a wrong report cannot change current behaviour. Do not call it when nothing went wrong.