treasury-fiscaldata-mcp-server

Browse the curated catalog of US Treasury Fiscal Data API endpoints. Returns endpoint paths, field names, descriptions, and update cadence for each dataset. Use this tool before treasury_query_dataset to discover the correct endpoint path and field names — a typo in either causes a 400 error from the API. The catalog is a curated subset of the full API — pass any endpoint path directly to treasury_query_dataset to query datasets not listed here. The catalog covers debt, interest rates, exchange rates, revenue/spending, savings bonds, and securities datasets.

{
  "type": "object",
  "properties": {
    "category": {
      "description": "Filter by category. Omit to list all datasets. Options: debt, interest_rates, exchange_rates, revenue_spending, savings_bonds, securities, other.",
      "type": "string",
      "enum": [
        "debt",
        "interest_rates",
        "exchange_rates",
        "revenue_spending",
        "savings_bonds",
        "securities",
        "other"
      ]
    },
    "search": {
      "description": "Keyword filter against dataset name and description (case-insensitive substring match). Useful for narrowing results when the category is uncertain.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "datasets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "endpoint": {
            "type": "string",
            "description": "Endpoint path to pass to treasury_query_dataset (e.g., \"/v2/accounting/od/debt_to_penny\"). Include the leading slash."
          },
          "name": {
            "type": "string",
            "description": "Human-readable dataset name."
          },
          "description": {
            "type": "string",
            "description": "What this dataset contains and when it is updated."
          },
          "category": {
            "type": "string",
            "description": "Broad category: debt, interest_rates, exchange_rates, revenue_spending, savings_bonds, securities, other."
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Field name as used in fields= and filter= parameters."
                },
                "label": {
                  "type": "string",
                  "description": "Human-readable label."
                },
                "type": {
                  "type": "string",
                  "description": "Data type (DATE, CURRENCY, PERCENTAGE, STRING, INTEGER, NUMBER, etc.)."
                }
              },
              "required": [
                "name",
                "label",
                "type"
              ],
              "additionalProperties": false,
              "description": "One field available on this endpoint."
            },
            "description": "Fields available on this endpoint."
          },
          "update_cadence": {
            "type": "string",
            "description": "How often the data is updated (e.g., \"Daily\", \"Monthly\", \"Quarterly\")."
          }
        },
        "required": [
          "endpoint",
          "name",
          "description",
          "category",
          "fields",
          "update_cadence"
        ],
        "additionalProperties": false,
        "description": "One dataset entry."
      },
      "description": "Matching datasets."
    },
    "total": {
      "type": "number",
      "description": "Total matching datasets."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "datasets",
        "total"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page. Call treasury_list_datasets first to get the correct endpoint path and exact field names — a typo in either causes a 400. Filter syntax: each condition is { field, operator, value } where operator is eq/gt/gte/lt/lte/in (e.g., record_date:gte:2024-01-01). Multiple conditions are ANDed together. All response values are strings per the API contract, including numbers and dates; "null" (string) means no value. Supply canvas_id to stage the page result as a DataCanvas table — read its column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query (requires CANVAS_PROVIDER_TYPE=duckdb on the server).

{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "string",
      "description": "Endpoint path returned by treasury_list_datasets (e.g., \"/v2/accounting/od/debt_to_penny\"). Include the leading slash."
    },
    "fields": {
      "description": "Fields to return. Omit to return all fields. Specify field names exactly as listed by treasury_list_datasets — a typo causes a 400.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "filters": {
      "description": "Filter conditions (ANDed together). Multiple filters on different fields are combined in one filter= parameter.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name to filter on."
          },
          "operator": {
            "type": "string",
            "enum": [
              "eq",
              "gt",
              "gte",
              "lt",
              "lte",
              "in"
            ],
            "description": "Comparison operator. \"in\" matches any value in the provided list."
          },
          "value": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "description": "Single filter value. Dates use YYYY-MM-DD format."
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "List of values for \"in\" operator."
              }
            ],
            "description": "Filter value. For \"in\", pass an array of strings. Dates use YYYY-MM-DD format."
          }
        },
        "required": [
          "field",
          "operator",
          "value"
        ],
        "additionalProperties": false,
        "description": "One filter condition."
      }
    },
    "sort": {
      "description": "Sort expression: field name optionally prefixed with \"-\" for descending (e.g., \"-record_date\" for newest-first).",
      "type": "string"
    },
    "page_size": {
      "default": 100,
      "description": "Rows per page. Default 100. Raise to 10000 to minimize round trips for small datasets. For large time-series pulls, use canvas_id with treasury_dataframe_query instead.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "page_number": {
      "default": 1,
      "description": "Page to fetch (1-indexed). Check total_pages in the response to know if more pages exist.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "canvas_id": {
      "description": "Set any non-empty value to stage this page as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Omit to receive results inline only. Requires CANVAS_PROVIDER_TYPE=duckdb on the server.",
      "type": "string"
    }
  },
  "required": [
    "endpoint"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "string",
      "description": "Endpoint that was queried."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "Rows returned. All values are strings per API contract — including numeric and date fields. Convert in the calling context. Null values appear as the string \"null\"."
    },
    "total_count": {
      "type": "number",
      "description": "Total rows matching the query (across all pages)."
    },
    "total_pages": {
      "type": "number",
      "description": "Total pages at the current page_size."
    },
    "page_number": {
      "type": "number",
      "description": "Current page (1-indexed)."
    },
    "page_size": {
      "type": "number",
      "description": "Rows per page."
    },
    "field_labels": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Human-readable label for each returned field."
    },
    "applied_filters": {
      "description": "Filter expression sent to the API, for verification.",
      "type": "string"
    },
    "canvas_id": {
      "description": "DuckDB table name (df_XXXXX_XXXXX) holding this page. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged.",
      "type": "string"
    },
    "canvas_expires_at": {
      "description": "ISO 8601 expiry for the canvas dataframe.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when results are empty, a field typo is suspected, the endpoint was not found in the catalog, or staging was requested.",
      "type": "string"
    },
    "totalCount": {
      "description": "Total rows matching the query across all pages — discloses that this page is a subset.",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_endpoint`: The endpoint path does not exist (API returns 404 HTML). `invalid_field`: A field name in fields= or filter= does not exist on this endpoint — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Field 'X' does not exist...\"}. `invalid_filter`: The filter expression uses an unsupported operator — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Operator ':op:' is not supported...\"}. `page_out_of_range`: page_number is past the last page of the matched set — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Page #N is out of range...\"}. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_endpoint",
                "invalid_field",
                "invalid_filter",
                "page_out_of_range"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "endpoint",
        "data",
        "total_count",
        "total_pages",
        "page_number",
        "page_size",
        "field_labels"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch national debt (Debt to the Penny) — total public debt outstanding broken into publicly-held debt and intragovernmental holdings. Three modes: "latest" returns the most recent business day's record; "date" returns the record for a specific date (must be a business day — the API only records debt on days markets are open); "series" returns a date range, staging the full result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query. Records go back to 1993-04-01.

{
  "type": "object",
  "properties": {
    "mode": {
      "default": "latest",
      "description": "\"latest\" returns the most recent day's record. \"date\" returns the record for a specific date. \"series\" returns a date range — use with start_date and end_date.",
      "type": "string",
      "enum": [
        "latest",
        "date",
        "series"
      ]
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD) for mode=date. Must be a business day; the API only records debt on days the market is open.",
      "type": "string"
    },
    "start_date": {
      "description": "ISO 8601 start date for mode=series (inclusive). Fiscal Data has daily debt records back to 1993-04-01.",
      "type": "string"
    },
    "end_date": {
      "description": "ISO 8601 end date for mode=series (inclusive). Defaults to today.",
      "type": "string"
    },
    "canvas_id": {
      "description": "Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when the range matches more than 500 rows. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "record_date": {
      "type": "string",
      "description": "Date of this debt record (YYYY-MM-DD). For series mode, the most recent date."
    },
    "total_debt": {
      "type": "string",
      "description": "Total public debt outstanding in USD, as a plain decimal string — no separators, no currency symbol, two decimal places. Convert as needed."
    },
    "debt_held_public": {
      "type": "string",
      "description": "Debt held by the public (external creditors, Fed, foreign governments) in USD."
    },
    "intragovernmental_holdings": {
      "type": "string",
      "description": "Intragovernmental holdings (debt owed to federal trust funds, Social Security, etc.) in USD."
    },
    "series": {
      "description": "Inline preview of the mode=series records — at most 20 rows, newest first. Compare series.length against retrieved_records to detect the cap; the full retrieved set is reachable through canvas_id when one is returned.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_date": {
            "type": "string",
            "description": "Date of this record (YYYY-MM-DD)."
          },
          "total_debt": {
            "type": "string",
            "description": "Total public debt outstanding in USD."
          },
          "debt_held_public": {
            "type": "string",
            "description": "Debt held by the public in USD."
          },
          "intragovernmental_holdings": {
            "type": "string",
            "description": "Intragovernmental holdings in USD."
          }
        },
        "required": [
          "record_date",
          "total_debt",
          "debt_held_public",
          "intragovernmental_holdings"
        ],
        "additionalProperties": false,
        "description": "One daily debt record."
      }
    },
    "total_records": {
      "description": "Records matching the date range upstream. Exceeds retrieved_records when the match is larger than the series row bound.",
      "type": "number"
    },
    "retrieved_records": {
      "description": "Records actually fetched for mode=series across every page, and the row count of the canvas table when one was registered. Never larger than total_records.",
      "type": "number"
    },
    "canvas_id": {
      "description": "DuckDB table name (df_XXXXX_XXXXX) holding the full retrieved series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged.",
      "type": "string"
    },
    "canvas_expires_at": {
      "description": "ISO 8601 expiry for the canvas dataframe.",
      "type": "string"
    },
    "truncated": {
      "description": "True when the inline series array holds fewer rows than were retrieved.",
      "type": "boolean"
    },
    "shown": {
      "description": "Series rows returned inline.",
      "type": "number"
    },
    "cap": {
      "description": "The preview cap applied to the inline series array.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when the inline series is a preview, when the series was staged as a DataCanvas table, or when paging stopped before the full matched set.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_data_for_date`: No debt record exists for the requested date (API returns HTTP 200 with empty data[], not 404 — total-count is 0). Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_data_for_date"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "record_date",
        "total_debt",
        "debt_held_public",
        "intragovernmental_holdings"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Average interest rates Treasury pays on its outstanding securities by security type. Answers "what is the government's cost of borrowing?" Covers every type Treasury reports — marketable issues, non-marketable series, and the aggregate totals — and which types it reports changes over the years, so omit security_type to see the ones a given period carries. Rates are percentages, not basis points. Updated monthly (end-of-month records). Mode "latest" returns the most recent month's rates for all or one security type; "series" returns a time history, staging the result as a DataCanvas table when canvas_id is set or the range matches more than 200 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query.

{
  "type": "object",
  "properties": {
    "mode": {
      "default": "latest",
      "description": "\"latest\" returns the most recent month's rates. \"series\" returns a time range.",
      "type": "string",
      "enum": [
        "latest",
        "series"
      ]
    },
    "security_type": {
      "description": "Filter to one security type, matched exactly against the security_desc field — full case and punctuation, as in \"Treasury Inflation-Protected Securities (TIPS)\". Omit for every type in the period, which is how to read the set of types on offer; the response names them when a filter matches nothing.",
      "type": "string"
    },
    "start_date": {
      "description": "ISO 8601 start date for mode=series (YYYY-MM-DD, must be end-of-month for meaningful results).",
      "type": "string"
    },
    "end_date": {
      "description": "ISO 8601 end date for mode=series. Defaults to today.",
      "type": "string"
    },
    "canvas_id": {
      "description": "Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when a series matches more than 200 rows. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "as_of_date": {
      "type": "string",
      "description": "Most recent record date returned (YYYY-MM-DD)."
    },
    "rates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_date": {
            "type": "string",
            "description": "Record date (YYYY-MM-DD)."
          },
          "security_type": {
            "type": "string",
            "description": "Security type (Marketable, Non-marketable, Interest-bearing Debt)."
          },
          "security_desc": {
            "type": "string",
            "description": "Security description (e.g., Treasury Bills)."
          },
          "avg_interest_rate_pct": {
            "type": "string",
            "description": "Average interest rate as a percentage string (e.g., \"3.696\"). Not basis points."
          }
        },
        "required": [
          "record_date",
          "security_type",
          "security_desc",
          "avg_interest_rate_pct"
        ],
        "additionalProperties": false,
        "description": "One interest rate record."
      },
      "description": "Interest rate records, newest first. Whole in mode=latest — a month is a bounded set. In mode=series an inline preview of at most 20 rows; compare its length against total_records to detect the cap, and reach the rest through canvas_id when one is returned."
    },
    "total_records": {
      "type": "number",
      "description": "In mode=latest, the number of rows in rates. In mode=series, the full upstream match — larger than rates.length whenever the preview cap applied."
    },
    "canvas_id": {
      "description": "DuckDB table name (df_XXXXX_XXXXX) holding the staged series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged.",
      "type": "string"
    },
    "canvas_expires_at": {
      "description": "ISO 8601 expiry for the canvas dataframe.",
      "type": "string"
    },
    "truncated": {
      "description": "True when the inline series array holds fewer rows than were retrieved.",
      "type": "boolean"
    },
    "shown": {
      "description": "Series rows returned inline.",
      "type": "number"
    },
    "cap": {
      "description": "The preview cap applied to the inline series array.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when no records match (where the requested security type does have records, or the types the most recent month carries, or the empty date range), when the inline series is a preview, or when the series was staged as a DataCanvas table.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "as_of_date",
        "rates",
        "total_records"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Official Treasury reporting exchange rates for ~165 countries — the rates US federal agencies are required to use when converting foreign currency to USD for official reporting. Published quarterly (March 31, June 30, Sep 30, Dec 31); mode "latest" returns the most recently published quarter. Rate is expressed as foreign currency units per 1 USD (e.g., a Japan-Yen rate of 159.41 means 1 USD = 159.41 JPY). These are NOT market exchange rates and are not suitable for financial transaction pricing. Mode "series" stages the result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query.

{
  "type": "object",
  "properties": {
    "mode": {
      "default": "latest",
      "description": "\"latest\" returns the most recently published quarter's rates. \"series\" returns a date range of quarterly reports.",
      "type": "string",
      "enum": [
        "latest",
        "series"
      ]
    },
    "countries": {
      "description": "Filter to specific countries by exact country name (e.g., [\"Japan\", \"Germany\", \"France\"]). Case-sensitive, matches the \"country\" field. Omit for every country in the quarter (~165).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start_date": {
      "description": "ISO 8601 start date for mode=series. Rates are published end-of-quarter (March 31, June 30, Sep 30, Dec 31).",
      "type": "string"
    },
    "end_date": {
      "description": "ISO 8601 end date for mode=series.",
      "type": "string"
    },
    "canvas_id": {
      "description": "Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when a series matches more than 500 rows, which multi-year multi-country pulls do (~19,000 rows for the full history). The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "as_of_date": {
      "type": "string",
      "description": "Most recent quarter-end record_date among the returned rows (YYYY-MM-DD). Not necessarily a date every row shares — check mixed_record_dates."
    },
    "effective_date": {
      "type": "string",
      "description": "Effective date of the as_of_date row (YYYY-MM-DD). Every row carries its own effective_date; this one does not describe the rest."
    },
    "mixed_record_dates": {
      "type": "boolean",
      "description": "True when the retrieved rows were not all published on as_of_date — including rows past the inline preview. Read each row's record_date rather than applying the top-level date to the set."
    },
    "rates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country name."
          },
          "currency": {
            "type": "string",
            "description": "Currency name."
          },
          "country_currency_desc": {
            "type": "string",
            "description": "\"Country-Currency\" combined label (e.g., \"Japan-Yen\"). Use for in= filter values."
          },
          "exchange_rate": {
            "type": "string",
            "description": "Foreign currency units per 1 USD. A value of 159.41 for Japan-Yen means 1 USD = 159.41 JPY."
          },
          "record_date": {
            "type": "string",
            "description": "Quarter-end record date this rate was published under (YYYY-MM-DD)."
          },
          "effective_date": {
            "type": "string",
            "description": "Date this rate takes effect (YYYY-MM-DD). Later than record_date when Treasury amends a rate mid-quarter, in which case the quarter carries more than one row for the country."
          }
        },
        "required": [
          "country",
          "currency",
          "country_currency_desc",
          "exchange_rate",
          "record_date",
          "effective_date"
        ],
        "additionalProperties": false,
        "description": "One exchange rate record."
      },
      "description": "Exchange rates for the requested countries/quarter, newest first. Whole in mode=latest — a quarter is a bounded set. In mode=series an inline preview of at most 20 rows; compare its length against retrieved_records to detect the cap, and reach the rest through canvas_id when one is returned."
    },
    "total_records": {
      "type": "number",
      "description": "In mode=latest, the number of rows in rates. In mode=series, the full upstream match — larger than rates.length whenever the preview cap applied, and larger than retrieved_records when paging stopped first."
    },
    "retrieved_records": {
      "description": "Rows actually fetched for mode=series across every page, and the row count of the canvas table when one was registered. Never larger than total_records.",
      "type": "number"
    },
    "note": {
      "type": "string",
      "description": "Contextual note reminding that these are official reporting rates, not market rates."
    },
    "canvas_id": {
      "description": "DuckDB table name (df_XXXXX_XXXXX) holding the staged series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged.",
      "type": "string"
    },
    "canvas_expires_at": {
      "description": "ISO 8601 expiry for the canvas dataframe.",
      "type": "string"
    },
    "truncated": {
      "description": "True when the inline rates array holds fewer rows than were retrieved.",
      "type": "boolean"
    },
    "shown": {
      "description": "Rate rows returned inline.",
      "type": "number"
    },
    "cap": {
      "description": "The preview cap applied to the inline rates array.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when a requested country matched no records, when the inline series is a preview, when the series was staged as a DataCanvas table, or when the returned rows were published in more than one quarter.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `country_not_found`: One or more requested countries have no records — API returns HTTP 200 with empty data[]; total-count is 0 or fewer countries were returned than requested. Other values are possible when a failure originates below the handler.",
              "examples": [
                "country_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "as_of_date",
        "effective_date",
        "mixed_record_dates",
        "rates",
        "total_records",
        "note"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List DataCanvas dataframes materialized by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, and column schema. Use this tool before treasury_dataframe_query to discover table names and column types. Requires CANVAS_PROVIDER_TYPE=duckdb.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Optional dataframe table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all active dataframes.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "dataframes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Canvas table name (df_XXXXX_XXXXX)."
          },
          "source_tool": {
            "type": "string",
            "description": "Treasury tool that produced this dataframe."
          },
          "query_params": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Input parameters the source tool was called with."
          },
          "created_at": {
            "type": "string",
            "description": "ISO 8601 creation timestamp."
          },
          "expires_at": {
            "type": "string",
            "description": "ISO 8601 expiry timestamp. Sliding TTL touched on every dataframe op."
          },
          "row_count": {
            "type": "number",
            "description": "Rows materialized in the dataframe."
          },
          "truncated": {
            "type": "boolean",
            "description": "True when the upstream source had more rows than were materialized."
          },
          "max_rows": {
            "description": "Materialization cap that produced `truncated`, when applicable.",
            "type": "number"
          },
          "column_schema": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "Canvas column type (VARCHAR, BIGINT, DOUBLE, ...). Treasury API values are VARCHAR."
                },
                "nullable": {
                  "type": "boolean",
                  "description": "Whether the column permits NULL (all Treasury columns are nullable)."
                }
              },
              "required": [
                "name",
                "type",
                "nullable"
              ],
              "additionalProperties": false,
              "description": "One column declaration in the dataframe schema."
            },
            "description": "Resolved column schema."
          }
        },
        "required": [
          "name",
          "source_tool",
          "query_params",
          "created_at",
          "expires_at",
          "row_count",
          "truncated",
          "column_schema"
        ],
        "additionalProperties": false,
        "description": "Provenance and schema for one dataframe."
      },
      "description": "Active dataframes for this tenant, newest first. Empty when none are registered."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: CANVAS_PROVIDER_TYPE is not set to duckdb. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "dataframes"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a single-statement SELECT against DataCanvas dataframes registered by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer. All Treasury dataframe columns are VARCHAR — CAST to DECIMAL or DATE for arithmetic and date comparisons. Use treasury_dataframe_describe to list available table names and column schemas before querying.

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "Single-statement SELECT against df_<id> tables. All values in Treasury dataframes are VARCHAR (strings) per the API contract — CAST to DECIMAL or DATE for arithmetic and date comparisons. Example: SELECT record_date, CAST(tot_pub_debt_out_amt AS DECIMAL) AS debt FROM df_xxxxx ORDER BY record_date DESC LIMIT 10."
    },
    "register_as": {
      "description": "Persist the result as a new dataframe under this exact name, to chain analyses. The name is used verbatim — any name works, and a df_ prefix keeps it consistent with the tables the data tools mint. Echoed back in registered_as.",
      "type": "string"
    },
    "preview": {
      "description": "Rows in the immediate response. Defaults to row_limit and may not exceed it. Set lower when using register_as.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "row_limit": {
      "default": 1000,
      "description": "Hard cap on rows the query may produce. Default 1000, max 10000. A query matching more rows than this stops at the cap and row_count_capped comes back true — raise it, or use register_as to materialize the whole result.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "columns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Column names in projection order."
    },
    "row_count": {
      "type": "number",
      "description": "Rows the query produced, up to row_limit. Exceeds rows.length when preview returned fewer. Read with row_count_capped: when that is true this number is row_limit itself, and the size of the full result is not in this response."
    },
    "row_count_capped": {
      "type": "boolean",
      "description": "True when the query matched more rows than row_limit, so row_count is that cap rather than a total. False means row_count is exact — including when it happens to equal row_limit."
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Materialized rows, bounded by preview / row_limit."
    },
    "registered_as": {
      "description": "Set when register_as was supplied and the new dataframe was materialized.",
      "type": "string"
    },
    "expires_at": {
      "description": "ISO 8601 expiry timestamp for the newly registered dataframe, when applicable.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when the query returned no rows, or when results were capped by preview or row_limit.",
      "type": "string"
    },
    "truncated": {
      "description": "True when the returned rows were capped below the full result set.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of rows returned in this response.",
      "type": "number"
    },
    "cap": {
      "description": "The row cap that was applied — preview when supplied, otherwise row_limit.",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: CANVAS_PROVIDER_TYPE is not set to duckdb. `system_catalog_access`: SQL references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*). `invalid_sql`: SQL is not a SELECT, contains DDL/DML, or uses disallowed table functions. `missing_table`: A df_<id> table named in the SQL is not on the canvas — its TTL expired, it was dropped, or it was never registered. `invalid_query_bounds`: preview exceeds row_limit, or row_limit exceeds the row ceiling this server allows. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_unavailable",
                "system_catalog_access",
                "invalid_sql",
                "missing_table",
                "invalid_query_bounds"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "columns",
        "row_count",
        "row_count_capped",
        "rows"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}