Brex

Assign one or more card expenses to a spend limit.

TERMINOLOGY: On Brex, these are called "limits" — NOT "budgets." There are two kinds: card limits (built into a card) and spend limits (exist independently). "Budget" is a separate Premium-only planning/tracking feature. When users say "budget" they almost always mean "limit." Prefer "limit" in responses unless the user is specifically asking about the Budget feature. The API returns fields named "budget_*" but these should be presented as "limits" to users.

Parameters:

• expense_ids: Array of card expense IDs to assign the limit to
• limit_id: The spend limit ID to assign to all expenses

Example (single card expense): { "expense_ids": ["card_exp_123"], "limit_id": "limit_123" }

Example (multiple card expenses with same limit): { "expense_ids": ["card_exp_123", "card_exp_456", "card_exp_789"], "limit_id": "limit_abc" }

Get the currently active accounting integration.

Returns null if no active accounting integration is found.

Example response: { "id": "SW50ZWdyYXRpb246NzEwOWU5YWMtYWRiZi00MGZjLTliMzMtZTE4OTBjYTk1MzM1", "vendor": "QuickBooks Online" }

Get detailed information about a specific banking transaction by its ID. Returns comprehensive transaction details including timeline, payment details, initiated/cancelled by user info, and cancellation status. Use list_banking_transactions first to find valid transaction IDs.

Example: { "transaction_id": "dptx_abc123" }

Get a bill (payable) by its ID.

Bills are invoices from vendors that need to be paid. This tool retrieves detailed information about a specific bill.

Parameters:

• id: The unique identifier of the bill

Example: { "id": "exp_abc123" }

Get a business account by its ID. Returns detailed information about a specific business account including balance breakdown and cashflow. Use list_business_accounts first to find valid account IDs.

Example: { "account_id": "dpacc_abc123" }

Get a card by its ID

Get an expense by its ID

Expand (receipt details):

• expand: Use ["RECEIPTS"] to include full receipt details. WITHOUT expand, receipts only contain IDs.

WITH expand: ["RECEIPTS"], each receipt includes:

• asset_id
• FileStore asset ID for the receipt file
• download_uri
• URL to download the receipt file/image
• content.is_real_receipt - whether the file is classified as a real receipt
• content.merchant_name - merchant name parsed from the receipt
• content.purchased_at - purchase date parsed from the receipt
• content.amount - amount parsed from the receipt
• content.line_items - itemized charges from the receipt (name, quantity, unit_price, total)

⚠️ When the user asks about receipt line items, itemized charges, "what did I buy", receipt content, receipt images/downloads, or parsed receipt data → you MUST include expand: ["RECEIPTS"]. A receipt with only an ID and no content/download_uri means expand was NOT used — re-call with expand: ["RECEIPTS"].

Additional Fields:

• additional_fields: Array of optional fields to include in response. Supported values:
• "TRAVEL_METADATA"
• Includes flight, car rental, lodging, and train travel data
• "LOCATION"
• Includes expense location details (country, city, coordinates, etc.)

IMPORTANT: Location and travel data are ALWAYS null unless you explicitly request them via additional_fields. A null location does NOT mean "no location exists" - it means you did not request it. If the user asks about where an expense occurred, you MUST call this tool again with additional_fields: ["LOCATION"]. Same for travel - use additional_fields: ["TRAVEL_METADATA"].

Example 1: Getting an expense with expanded receipts (includes line items, download URL, parsed content): { "id": "expense_123", "expand": ["RECEIPTS"] }

Example 2: Getting an expense with travel metadata and location: { "id": "expense_123", "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Example 3: Getting an expense with everything: { "id": "expense_123", "expand": ["RECEIPTS"], "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Understanding Expense Lifecycle and Compliance Status:

Expense Lifecycle: 1. New expense created (card transaction or reimbursement submitted) 2. Documentation phase: System checks if documentation is required (receipts, memo, attendees, etc.) 3. Spender submits documentation if needed 4. Review phase: System checks if approval/review is required based on company policy 5. Reviewer reviews and approves/rejects if necessary 6. Expense is finalized

Each expense returns TWO sets of compliance-related fields:

A. DOCUMENTATION COMPLIANCE (for spenders - receipts, memo, attendees):

• documentationComplianceStatus: Status of documentation requirements that the spender must fulfill
• "NOT_REQUIRED"
• Company policy does not require any documentation for this expense. Empty receipts/memo are acceptable.
• "COMPLETED"
• All required documentation has been provided according to policy.
• "DUE"
• Documentation is required by policy but not yet provided. Check missingDocumentations field for specifics.
• "OVERDUE"
• Required documentation is past its submission deadline. Check missingDocumentations field for specifics.
• missingDocumentations: Array of specific items required by policy but not yet provided. Possible values: ["MEMO", "RECEIPT", "ATTENDEES", "EXTENDED_FIELD"]
• Empty array []
• Either no documentation is required OR all required documentation is complete
• Non-empty array
• Lists specific items that must be provided (e.g., ["MEMO", "RECEIPT"])
• documentationSubmissionDeadline: The UTC timestamp by which documentation must be submitted (only present if documentation is required)

B. REVIEW COMPLIANCE (for reviewers - approval/rejection):

• reviewComplianceStatus: Status of review/approval requirements that the reviewer must fulfill
• "NOT_REQUIRED"
• Company policy does not require review/approval for this expense.
• "COMPLETED"
• The expense has been reviewed and approved/rejected.
• "DUE"
• Review is required by policy but not yet completed.
• "OVERDUE"
• Required review is past its deadline.
• reviewDeadline: The UTC timestamp by which the review must be completed (only present if review is required)

KEY DISTINCTIONS:

• DocumentationComplianceStatus="NOT_REQUIRED" and missingDocumentations=[] → Documentation not required by company policy
• Empty receipts/memo with documentationComplianceStatus="DUE" or "OVERDUE" and missingDocumentations=["RECEIPT","MEMO"] → Documentation IS required by policy but missing
• reviewComplianceStatus="DUE" or "OVERDUE" → Expense is waiting for someone to review/approve it
• reviewComplianceStatus="NOT_REQUIRED" → No approval needed

Check the status of an expense download job and get the download URL when ready.

Call this after start_expense_download to poll for completion. Download jobs typically take 10-300 seconds.

Response statuses:

• PROCESSING: Job is still running. Poll again after waiting
• COMPLETED: Job finished successfully. The download_url field contains a URL to download the CSV file.
• FAILED: Job failed. The error field contains the failure reason

IMPORTANT: Recommended polling strategy: 1. Wait 5 seconds after calling start_expense_download 2. Poll every 10 seconds until status is COMPLETED or FAILED 3. Maximum expected duration: 5 minutes

The CSV file includes 15 columns: Parent ID, Flagged Expenses, Transaction Date, Expense Type, Card Last 4, Amount, Currency, Original Amount, Original Currency, Merchant Name, User, Budget Name, Memo, Expense Status, Payment Status.

If fetching download_url fails after status is COMPLETED: The signed URL is valid and reusable. The most common cause of a download failure is that the client environment blocks outbound requests to external hosts. If the client has a domain/URL allowlist (e.g., Claude Code Web's "Allowed domains" setting), the user must add api.brex.com to it before the fetch will succeed. After allowlisting, simply retry the fetch — there is no need to re-run start_expense_download.

Parameters:

• job_id (required): The job ID returned by start_expense_download

Get expense policy information for a limit as structured, validatable content.

TERMINOLOGY: On Brex, these are called "limits" — NOT "budgets." There are two kinds: card limits (built into a card) and spend limits (exist independently). "Budget" is a separate Premium-only planning/tracking feature. When users say "budget" they almost always mean "limit." Prefer "limit" in responses unless the user is specifically asking about the Budget feature. The API returns fields named "budget_*" but these should be presented as "limits" to users.

This tool returns expense policy rules in the EXACT same format as shown in the Brex Dashboard's "View policy" sidebar, but structured as JSON for proper validation.

What you'll get:

• formatted_text: Human-readable policy text matching Dashboard display
• sections: Array of policy sections with rules
• has_restrictions: Boolean indicating if there are any policy restrictions
• budget_name: Name of the limit
• policy_name: Name of the policy

Use this tool to answer questions like:

• "Do I need a receipt for this $30 lunch?"
• "Can I expense alcohol?"
• "Who needs to approve my $500 dinner?"
• "What's the limit before I need approval?"
• "Do I need to list attendees for a business meal?"
• "Can I expense Uber Eats?"
• "What's the approval policy?"

IMPORTANT: This tool requires a spend_limit_id. When the user asks policy questions without specifying a limit: 1. First call list_my_limits to get available limit IDs 2. If there's only one limit, use its ID automatically 3. If there are multiple limits and the user didn't specify which one, ask for clarification

Parameters:

• spend_limit_id: REQUIRED
• The ID of the limit. Use the ID directly from list_my_limits response.
• rules_filter: OPTIONAL
• Which view of the policy to return:
• "ONLY_RELEVANT_FOR_REQUESTER" (default): Shows personalized rules for the requesting user
• "ALL_RULES": Shows complete policy including all user-specific exceptions (requires admin permissions)

Response Format: Returns structured JSON with:

• formatted_text: Natural language policy rules
• sections: Array of {title, type, description, rules[]}
• has_restrictions: boolean
• budget_name: string
• policy_name: string

Get the expected payout date for a reimbursement expense. Returns the date when the reimbursement payment is expected to arrive. Only works for REIMBURSEMENT type expenses that are paid through Brex.

Note: This tool will return an error if the reimbursement is configured to be paid outside of Brex (Pay outside of Brex / PoB). In those cases, the payment is handled directly between the company and employee (usually at payroll time), and Brex does not control the payment date.

Parameters:

• expense_id: The ID of the reimbursement expense

Example: { "expense_id": "expense_123" }

Response includes:

• expense_id: The ID of the expense
• expense_type: The type of the expense (will be REIMBURSEMENT)
• expected_reimbursement_payout_date: The expected date when the reimbursement will be paid out (ISO 8601 format, UTC timezone)
• status: The current status of the expense

Get the Brex reward points balance and redemption eligibility for the authenticated account.

Returns the current reward balance, wallet type (POINTS or CASH), and whether the account can currently redeem rewards.

Parameters: none.

Example response: { "amount": 2781573647, "type": "POINTS", "redeemable": true }

Notes:

• "amount" is in centipoints when "type" is POINTS (divide by 100 to get points).
• "amount" is in USD cents when "type" is CASH.
• "redeemable" is false if the account is delinquent.

Get a user by their unique ID

This tool retrieves detailed information about a specific user using their unique user ID. Use this when you have a user ID and need to get their complete profile information.

Example Input: { "id": "cuuser_123" }

Example Output: { "id": "cuuser_123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE", "manager_id": "cuuser_5678", "manager_first_name": "Jane", "manager_last_name": "Smith", "manager_title_id": "ti_1234", "manager_title_name": "Engineering Manager", "department_id": "cudmnt_1234", "department_name": "Engineering", "location_id": "culoc_1234", "location_name": "San Francisco", "title_id": "ti_5678", "title_name": "Software Engineer" }

Get the current authenticated user

This tool retrieves the profile information of the currently authenticated user making the request. Use this when you need to get information about who is currently logged in or making the API call. No input parameters required.

Example Output: { "id": "cuuser_123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE" }

Get a vendor by ID

List accounting records with filters and pagination.

This tool returns accounting records with the full record shape, including amounts, source information, users, vendors, receipts, and line items.

Supported filters:

• ids: specific accounting record IDs
• review_status: workflow stage for CARD and REIMBURSEMENT records
• source_type: high-level source filter such as CARD, REIMBURSEMENT, or BILL
• updated_at: gt/gte/lt/lte timestamp filters for polling
• erp_posting_date: inclusive from/to timestamp filters for ERP posting date (accruedAt) range
• timezone: IANA timezone for interpreting date-only and local datetime filters; defaults to UTC
• single_entry: return single-entry line items instead of the default double-entry view
• cursor and limit: pagination controls

Date filters accept date-only strings (e.g., "2025-05-06"), local datetimes (e.g., "2025-05-06T14:00:00"), or UTC/offset datetimes. Date-only and local datetime values are converted to UTC using timezone. Always tell the user which timezone was used when presenting date-filtered results.

Constraint:

• review_status is not supported with source_type=BILL

List banking transactions with filters, date ranges, amount ranges, and sorting. If the user mentions an account by name, use list_business_accounts first to resolve the name to an ID. Results are paginated - use limit and cursor for pagination.

IMPORTANT: Transaction amounts use signed convention:

• Positive amounts = incoming money (credits/deposits)
• Negative amounts = outgoing money (debits/payments)

For incoming transactions (money received), use positive min_amount. For outgoing transactions (money sent/paid), use negative max_amount.

CRITICAL

• Amount filter decision logic:

🔍 When the user mentions amounts, ALWAYS include the appropriate filter:

"Over $X" or "More than $X":

• Incoming: min_amount: X (e.g., "deposits over $100" → min_amount: 100)
• Outgoing: max_amount: -X (e.g., "payments over $1000" → max_amount: -1000)

"Between $X and $Y":

• MUST include BOTH min_amount AND max_amount
• Incoming: min_amount: X, max_amount: Y (e.g., "deposits between $100 and $500")
• Outgoing: min_amount: -Y, max_amount: -X (e.g., "payments between $100 and $500" → min_amount: -500, max_amount: -100)

"Under $X" or "Less than $X":

• Incoming: max_amount: X
• Outgoing: min_amount: -X

Example 1: Getting recent transactions sorted by timestamp: { "sort": "TIMESTAMP", "sort_direction": "DESCENDING" }

Example 2: Getting ACH transactions for a specific account: { "business_account_ids": ["dpacc_abc123"], "type": ["ACH"] }

Example 3: Incoming transactions over $100 (deposits/credits): { "start_date": "2025-01-01T00:00:00Z", "end_date": "2025-01-31T23:59:59Z", "min_amount": 100.00 }

Example 4: Outgoing payments over $1,000 (debits): { "max_amount": -1000.00, "sort": "AMOUNT_USD_CENTS", "sort_direction": "ASCENDING", "limit": 10 }

Example 5: Account transfers between Brex accounts: { "type": ["ACCOUNT_TRANSFER", "BOOK_TRANSFER"] }

Example 6: Only processed transactions: { "status": ["PROCESSED"] }

Example 7: Pending transactions (processing or awaiting approval): { "status": ["PROCESSING", "APPROVAL_REQUIRED"] }

List bills for your team members or entire company based on permissions.

This tool allows managers and admins to retrieve bills using different scopes.

By default, returns bills with statuses: DRAFT, SUBMITTED, APPROVED, OUT_OF_POLICY, CANCELED, VOID.

Parameters:

• vendor_id: Optional vendor ID to filter bills by a specific vendor
• incurred_by: Determines whose bills to show (optional). Options:
• Not specified: All bills you have permission to see (for admins/bookkeepers: all company bills)
• "REPORTS": Bills from your direct reports only
• "ALL_REPORTS": Bills from all nested reports (your reports + their reports)

Note: Regular users without reports will get no results when using REPORTS/ALL_REPORTS.

• statuses: Optional array of expense statuses to filter by (bills are expenses with type=BILLPAY).

Supported values: DRAFT, SUBMITTED, APPROVED, OUT_OF_POLICY, CANCELED, VOID. If not specified, defaults to DRAFT, SUBMITTED, APPROVED, OUT_OF_POLICY, CANCELED, and VOID.

• limit: Number of results to return (default: 15, max: 100)
• cursor: Pagination cursor for next page of results

Example 1: Get ALL company bills (admin/bookkeeper access): { "limit": 50 }

Example 2: Get bills from direct reports: { "incurred_by": "REPORTS", "statuses": ["DRAFT", "SUBMITTED"] }

Example 3: Get all team bills (including nested reports): { "incurred_by": "ALL_REPORTS" }

Example 4: Get all company bills from a specific vendor: { "vendor_id": "vendor_abc123" }

List travel bookings across the company with filtering, sorting, and pagination.

Mirrors the Bookings page on the Brex dashboard (Travel → Company → Bookings). Use this tool when the user asks specifically about individual bookings (flights, hotels, car rentals) rather than whole trips.

Results are always sorted by booking start date descending.

Filters are grouped to match the dashboard:

General:

• booking_start_date_on_or_after / booking_start_date_on_or_before: Booking start date. Date (YYYY-MM-DD) bounding the booking start date (local).
• booking_types: Booking type. Array of booking categories (AIR, CAR_RENTAL, LIMO, LODGING, MISC, RAIL).

People:

• booker_user_ids: Booker. Array of booker (employee) user IDs (cuuser_*) to filter by specific bookers.
• traveler_user_ids: Traveler. Array of traveler user IDs (cuuser_*) to filter by traveler.
• traveler_guest_emails: Traveler. Array of guest traveler emails to filter by traveler.
• traveler_types: Traveler type. Array of ["EMPLOYEE", "GUEST"] to narrow by traveler type.

Status:

• booking_statuses: Booking status. Array of booking statuses (CONFIRMED, PENDING, CANCELED, etc.).
• approval_statuses: Approval status. Array of approval statuses (APPROVED, PENDING, REJECTED).
• policy_statuses: Policy status. Array (IN_POLICY, OUT_OF_POLICY).

Pagination:

• limit: Page size (default 25, max 100).
• cursor: Cursor from a previous response's next_cursor.

Example: { "booking_types": ["AIR"], "booking_statuses": ["CONFIRMED"] }

List business accounts. Results are paginated - use limit and cursor for pagination.

Example 1: Getting the first 10 accounts: { "limit": 10 }

Example 2: Paginating through accounts: { "limit": 25, "cursor": "cursor_from_previous_response" }

List cards with comprehensive filtering. Use this for both personal card queries and company-wide card management.

🔍 IMPORTANT

• How to scope card queries with card_holder:

Personal queries (use card_holder: "ME"):

• "my cards", "my locked cards", "do my cards have..."
• "which of my cards is active"
• "show me my cards"

→ SET card_holder: "ME" to return only the calling user's cards

IMPORTANT DEFAULT BEHAVIOR: When the query is ambiguous (no explicit "company/all/team" scope), default to card_holder: "ME" since users typically want their own cards.

Company-wide queries (omit card_holder):

• "all company cards", "list all cards", "company card inventory"

→ OMIT card_holder to return all cards across the organization (admin only)

Specific user queries (use user_ids):

• "John's cards", "show Alice's cards"

→ First call list_users_by_name_or_email to get user ID, then pass user_ids parameter

You can filter by status views (ACTIVE, EXPIRED, LOCKED, TERMINATED, WAITING_ACTIVATION) and card holder user IDs. Results are paginated - use limit and cursor for pagination.

IMPORTANT: card_holder and user_ids are mutually exclusive. Use card_holder for self-scoping or user_ids for specific user IDs, but not both.

Example 1: Getting all my active cards: { "card_holder": "ME", "status": ["ACTIVE"] }

Example 2: Getting all my cards (any status): { "card_holder": "ME" }

Example 3: Getting all active cards (admin): { "status": ["ACTIVE"] }

Example 4: Getting all active and locked cards for specific users: { "status": ["ACTIVE", "LOCKED"], "user_ids": ["user_123"] }

Example 5: Getting cards for a specific user: { "user_ids": ["user_123"] }

List cost centers (id + display name).

REQUIRED prerequisite for the list_users cost_center filter: list_users only accepts cost center IDs, so whenever the user mentions a cost center by name (e.g. "R&D", "Sales"), call this tool first and pass the returned id into list_users.

Parameters: limit (1-200, default 25), cursor (pagination), search_text (narrow by name).

Example Output: { "items": [{ "id": "cc_1234", "name": "Engineering" }], "next_cursor": "cursor_abc" }

List departments (id + name).

REQUIRED prerequisite for the list_users department filter: list_users only accepts department IDs, so whenever the user mentions a department by name (e.g. "Engineering", "Finance"), call this tool first and pass the returned id into list_users.

Parameters: limit (1-200, default 25), cursor (pagination), search_text (narrow by name).

Example Output: { "items": [{ "id": "cudmnt_1234", "name": "Engineering" }], "next_cursor": "cursor_abc" }

List all available expense categories (also known as 'expense types' in Brex) for filtering expenses.

Expense categories are custom categorizations like:

• Airfare, Lodging, Car Rental (travel)
• Meals & Entertainment
• Office Supplies
• Software & SaaS
• Marketing & Advertising
• Professional Services

Use this tool to:

• Discover available expense category IDs for the expense_category_ids filter
• Search categories by name (e.g., "travel", "meals")
• Browse all configured expense categories

Parameters:

• query: Optional search to filter by name (e.g., "travel", "meals")
• limit: Page size (default 25, max 100)
• cursor: Pagination cursor from previous response

Example — find travel categories: { "query": "travel" }

Response (trimmed): { "items": [ { "id": "category_abc", "name": "Airfare" }, { "id": "category_def", "name": "Car Rental" } ], "next_cursor": null }

List expenses with comprehensive filtering. Use this for both personal expense queries and company-wide financial analysis.

IMPORTANT

• For large datasets (50+ expenses): If your environment supports downloading files from URLs, consider using start_expense_download for CSV export instead to avoid loading hundreds of records into conversation context. This tool returns paginated results suitable for smaller queries and interactive workflows.

IMPORTANT

• How to scope expense queries with expense_owner:

🔍 The primary users of this tool are admins and finance operators, so the DEFAULT SCOPE is company-wide. Only narrow to the caller when the user explicitly says so.

IMPORTANT DEFAULT BEHAVIOR: When the query is ambiguous or phrased generically (no possessive "my"/"mine" and no subject "I"), OMIT expense_owner. This returns all expenses across the organization, which is what admins asking questions like "show expenses over $500", "find expenses missing receipts", "which expenses are declined" expect.

⚠️ Do NOT treat "show me X" as a personal-scope signal. "me" is just the indirect object of "show" — it does NOT imply the user owns the expenses. Only the possessive "my"/"mine" or the subject "I" indicate personal scope.

Personal queries ONLY when the user explicitly refers to themselves (use expense_owner: "ME"):

• Possessive: "my expenses", "my receipts", "my reimbursements", "my card transactions", "which of my expenses..."
• Subject "I": "how much have I spent", "what did I spend on...", "am I spending more on..."
• Do NOT infer personal scope from: "show expenses", "find expenses", "list expenses", "which expenses", "show me expenses", "expenses over $X", "expenses from [merchant]"

→ SET expense_owner: "ME" ONLY when the user message contains "my", "mine", or "I" as a subject referring to the caller

Company-wide queries (OMIT expense_owner — this is the default):

• Any request without a first-person pronoun: "show expenses", "find expenses missing receipts", "which expenses are flagged", "list card expenses over $500"
• Explicit company language: "our burn rate", "we spent", "company expenses", "overall spending", "analyze all card transactions", "total reimbursements"

→ OMIT expense_owner to return all expenses across the organization

Team queries (use expense_owner: "DIRECT_REPORTS" or "ALL_REPORTS"):

• "my team's expenses", "direct reports' spending"
• "expenses from all my reports"

→ Use DIRECT_REPORTS for immediate reports only, or ALL_REPORTS for nested reports

Specific user queries (use user_ids):

• "show John's expenses", "Alice's reimbursements"

→ First call list_users_by_name_or_email to get user ID, then pass user_ids parameter

IMPORTANT

• Location and travel data:

🌍 Location and travel data are ALWAYS null by default unless you explicitly request them via additional_fields.

When user asks about WHERE an expense occurred (location, city, country, address):

• Query asks: "Where was that expense?", "What city was this from?", "Show me the location"

→ You MUST include additional_fields: ["LOCATION"]

When user asks about travel details (flights, hotels, car rentals):

• Query asks: "Was this a flight?", "Show me travel expenses", "Which hotel?"

→ You MUST include additional_fields: ["TRAVEL_METADATA"]

⚠️ A null location does NOT mean "no location exists" - it means you did not request it in additional_fields.

expense types (BILLPAY, CARD, CLAWBACK, REIMBURSEMENT),

Filter Usage Best Practices:

• For CARD expense queries, always include date filters (purchased_at_start/purchased_at_end) for reliable results
• When using min_amount/max_amount filters, combine with date filters for better performance

Timezone:

• timezone: IANA timezone string (e.g., "America/Los_Angeles", "America/New_York", "Europe/London", "Asia/Tokyo").

Pass the user's timezone from your system context if available. If not provided, defaults to UTC.

IMPORTANT

• Transparency: When presenting results, ALWAYS tell the user which timezone was used for the query:
• If timezone was provided: "Based on your Pacific Time zone, here are expenses from May 6, 2026..."
• If timezone was NOT provided (UTC default): "Note: dates are interpreted in UTC. If you'd like results in your local timezone, let me know your timezone."

Why this matters: When a user says "show this week's expenses", they mean their local week. The timezone parameter ensures date filters match the user's local calendar days. Without it, dates are treated as UTC which may not match the user's intent.

Date Filtering (only one type can be used at a time): IMPORTANT

• Default to purchased_at for ALL time-based queries. The purchased_at filter covers when the transaction actually occurred and is the correct filter for general date queries like "this week", "last month", "recent", "posted this week", etc. Only use posted_at when the user explicitly needs the bank settlement/accounting posting date for reconciliation purposes.
• Purchase Date (DEFAULT): purchased_at_start/purchased_at_end
• Filter by when expense was purchased/transacted. Use this for all general date queries. Pass dates/datetimes in the user's local timezone (will be converted to UTC automatically).
• Posted Date (accounting only): posted_at_start/posted_at_end
• Filter by bank settlement/posting date. Only use when user specifically needs accounting posting dates. Pass dates/datetimes in the user's local timezone (will be converted to UTC automatically).
• Reimbursement Submission Date: reimbursement_submitted_at_start/reimbursement_submitted_at_end
• Filter by when reimbursement was submitted (only works with REIMBURSEMENT type). Pass dates/datetimes in the user's local timezone (will be converted to UTC automatically).
• Assigned Date: assigned_at_start/assigned_at_end
• Filter by when expense was assigned for review. Pass dates/datetimes in the user's local timezone (will be converted to UTC automatically).

Amount Filtering (all amounts in USD):

• min_amount: Filter expenses with amount greater than or equal to this value (in USD, supports decimals with up to 2 places)
• max_amount: Filter expenses with amount less than or equal to this value (in USD, supports decimals with up to 2 places)

Text Search:

• search: Search expenses by merchant name, memo, or other text fields (e.g., "nike", "lunch")

Limit Filtering:

• limit_ids: Filter expenses by spend limit IDs (e.g., ["limit_123", "limit_456"])

CRITICAL: This parameter ONLY accepts limit IDs (like "spl_abc123"). It does NOT accept limit names (like "Tony's T&E"). If the user mentions a limit by name, you MUST first call list_my_limits to resolve the name to an ID, then pass that ID here. NEVER pass a limit name directly to this parameter - it will not work correctly.

Expense ID Filtering:

• expense_ids: Filter by specific expense IDs (e.g., ["expense_123", "expense_456"])

Additional Fields:

• additional_fields: Array of optional fields to include in response. Supported values:
• "TRAVEL_METADATA"
• Includes flight, car rental, lodging, and train travel data
• "LOCATION"
• Includes expense location details (country, city, coordinates, etc.)

Note: Location and travel data are NOT returned by default. If the response has null location/travel and the user is asking about it, re-call with the relevant additional_fields value.

Expense records include associated card details (card ID, status, last four digits) when available - you do not need to separately look up cards to answer questions about expenses on specific cards.

IMPORTANT: expense_owner and user_ids are mutually exclusive. Use expense_owner for role-based scoping or user_ids for specific user IDs, but not both.

Expand (receipt details):

• expand: Use ["RECEIPTS"] to include full receipt details. WITHOUT expand, receipts only contain IDs.

WITH expand: ["RECEIPTS"], each receipt includes:

• asset_id
• FileStore asset ID for the receipt file
• download_uri
• URL to download the receipt file/image
• content.is_real_receipt - whether the file is classified as a real receipt
• content.merchant_name - merchant name parsed from the receipt
• content.purchased_at - purchase date parsed from the receipt
• content.amount - amount parsed from the receipt
• content.line_items - itemized charges from the receipt (name, quantity, unit_price, total)

⚠️ When the user asks about receipt line items, itemized charges, "what did I buy", receipt content, receipt images/downloads, or parsed receipt data → you MUST include expand: ["RECEIPTS"]. A receipt with only an ID and no content/download_uri means expand was NOT used — re-call with expand: ["RECEIPTS"].

Status Filters:

• approval_statuses: Filter by approval status. Dashboard-exposed values: APPROVED, CANCELED, OUT_OF_POLICY, SUBMITTED.
• pending_approvals: FROM_ME (pending your approval) or FROM_OTHERS (pending another approval).
• payment_statuses: Payment lifecycle state (NOT_STARTED, SCHEDULED, PROCESSING, CANCELED, CLEARED, DECLINED, REFUNDING, REFUNDED, CASH_ADVANCE, CREDITED, AWAITING_PAYMENT).
• dispute_statuses: Dashboard-exposed values: DISPUTE_STATUS_IN_PROGRESS, DISPUTE_STATUS_CLOSED.
• reimbursement_export_statuses: EXPORTED or NOT_EXPORTED (reimbursement export state).
• user_status: Filter by spender's user status. Dashboard-exposed: ACTIVE, DELETED, DISABLED.

Reimbursement-only filters (require types: ["REIMBURSEMENT"]):

• reimbursement_types: MILEAGE, OUT_OF_POCKET, PER_DIEM.
• reimbursement_payment_method: MONEY_MOVEMENT (paid on Brex) or TRACKING (paid outside of Brex).

Travel filters:

• travel_provider: BREX_TRAVEL (only Brex Travel) or NON_BREX_TRAVEL (exclude Brex Travel).
• trip_ids: Filter by trip IDs — use list_active_and_upcoming_travel_trips to discover IDs.

Compliance Filters (matches dashboard labels):

• compliance_statuses: Overall compliance status (DOCUMENTATION_DUE, REVIEW_DUE, COMPLETED). Matches the 'Compliance status' filter in the Brex dashboard.
• documentation_statuses: Documentation deadline status (DUE, OVERDUE, COMPLETED). Matches the 'Documentation status' filter in the Brex dashboard. Use [DUE, OVERDUE] to find expenses missing required documentation.
• receipt_status: RECEIPT_PRESENT or RECEIPT_ABSENT.
• memo_status: MEMO_PRESENT or MEMO_ABSENT.
• require_review_reasons: MEALS, CAR_RENTAL (Rides), FLIGHTS, LODGING, TRAINS, MILEAGE, MERCHANT_OR_CATEGORY, AMOUNT, OTHERS.
• government_attendees_status: GOVERNMENT_OFFICIAL_PRESENT or GOVERNMENT_OFFICIAL_ABSENT.
• expense_policy_ids: Filter by policy IDs — use get_expense_policy to inspect a specific policy.
• bill_invoice_numbers: Filter Bill Pay expenses by invoice number (free text).

Approver / Approval filters:

• approver_user_ids: Filter by approvers in the approval chain — resolve user IDs via list_users_by_name_or_email.
• next_approver_user_ids: Filter by the next approver in the chain — resolve user IDs via list_users_by_name_or_email.

Organization Filters:

• department_ids: Filter by department IDs — use list_departments to discover IDs.
• card_ids: Filter by card IDs (use this when the user mentions a card by last-4).
• vendor_ids: Bill Pay vendor IDs — use list_vendors to discover.
• merchant_ids: Card merchant IDs — use list_merchants to discover.
• merchant_category_ids: Merchant category IDs — use list_merchant_categories to discover.

Accounting Filters:

• billing_entity_ids: Filter by billing (funding) legal entity IDs. Also called 'billed entity' in the Dashboard.
• spending_entity_ids: Filter by spending legal entity IDs.
• cost_center_ids: Filter by cost center IDs.
• expense_category_ids: Filter by expense category IDs — use list_expense_categories to discover IDs.
• erp_debit_gl_account_field_key + erp_debit_gl_account_option_ids: Filter by ERP debit GL account. These two parameters MUST be sent together. Workflow: (1) call list_gl_accounts, (2) copy gl_account_field.key into erp_debit_gl_account_field_key, (3) copy the desired accounts[].identifier values (not id, not value) into erp_debit_gl_account_option_ids. Never guess the field_key — it is dynamic per accounting integration.

Risk Filter:

• high_risk_flagged: When true, only returns expenses flagged as HIGH risk. Omit (or false) to not filter by risk tier.

Date Filters (use only ONE of purchased/posted/reimbursement_submitted at a time; assigned_at is independent):

• assigned_at_start / assigned_at_end: Date expense was assigned to the caller for review.

Understanding Expense Lifecycle and Compliance Status:

Expense Lifecycle: 1. New expense created (card transaction or reimbursement submitted) 2. Documentation phase: System checks if documentation is required (receipts, memo, attendees, etc.) 3. Spender submits documentation if needed 4. Review phase: System checks if approval/review is required based on company policy 5. Reviewer reviews and approves/rejects if necessary 6. Expense is finalized

Each expense returns TWO sets of compliance-related fields:

A. DOCUMENTATION COMPLIANCE (for spenders - receipts, memo, attendees):

• documentationComplianceStatus: Status of documentation requirements that the spender must fulfill
• "NOT_REQUIRED"
• Company policy does not require any documentation for this expense. Empty receipts/memo are acceptable.
• "COMPLETED"
• All required documentation has been provided according to policy.
• "DUE"
• Documentation is required by policy but not yet provided. Check missingDocumentations field for specifics.
• "OVERDUE"
• Required documentation is past its submission deadline. Check missingDocumentations field for specifics.
• missingDocumentations: Array of specific items required by policy but not yet provided. Possible values: ["MEMO", "RECEIPT", "ATTENDEES", "EXTENDED_FIELD"]
• Empty array []
• Either no documentation is required OR all required documentation is complete
• Non-empty array
• Lists specific items that must be provided (e.g., ["MEMO", "RECEIPT"])
• documentationSubmissionDeadline: The UTC timestamp by which documentation must be submitted (only present if documentation is required)

B. REVIEW COMPLIANCE (for reviewers - approval/rejection):

• reviewComplianceStatus: Status of review/approval requirements that the reviewer must fulfill
• "NOT_REQUIRED"
• Company policy does not require review/approval for this expense.
• "COMPLETED"
• The expense has been reviewed and approved/rejected.
• "DUE"
• Review is required by policy but not yet completed.
• "OVERDUE"
• Required review is past its deadline.
• reviewDeadline: The UTC timestamp by which the review must be completed (only present if review is required)

KEY DISTINCTIONS:

• DocumentationComplianceStatus="NOT_REQUIRED" and missingDocumentations=[] → Documentation not required by company policy
• Empty receipts/memo with documentationComplianceStatus="DUE" or "OVERDUE" and missingDocumentations=["RECEIPT","MEMO"] → Documentation IS required by policy but missing
• reviewComplianceStatus="DUE" or "OVERDUE" → Expense is waiting for someone to review/approve it
• reviewComplianceStatus="NOT_REQUIRED" → No approval needed

All dates should be in ISO 8601 format (e.g., "2025-04-01" or "2025-04-01T14:00:00") in the user's local timezone. They will be automatically converted to UTC using the timezone parameter. All amounts are assumed to be in USD currency. Results are paginated - use limit and cursor for pagination.

Example 1: Analyze company monthly burn rate (all card spend in March 2025): { "types": ["CARD"], "purchased_at_start": "2025-03-01T00:00:00.000Z", "purchased_at_end": "2025-03-31T23:59:59.999Z" }

Example 2: Find all high-dollar expenses over $5,000 in Q1 2025: { "min_amount": 5000, "purchased_at_start": "2025-01-01T00:00:00.000Z", "purchased_at_end": "2025-03-31T23:59:59.999Z" }

Example 3: Analyze SaaS/software spending (search for common software vendors): { "search": "AWS", "types": ["CARD"], "purchased_at_start": "2025-01-01T00:00:00.000Z", "purchased_at_end": "2025-12-31T23:59:59.999Z" }

Example 4: Review all pending reimbursements awaiting payout: { "types": ["REIMBURSEMENT"] }

Example 5: Analyze travel spending across the company (exclude Brex Travel): { "types": ["CARD"], "travel_provider": "NON_BREX_TRAVEL", "additional_fields": ["TRAVEL_METADATA"], "purchased_at_start": "2025-01-01T00:00:00.000Z", "purchased_at_end": "2025-03-31T23:59:59.999Z" }

Example 6: Find expenses missing receipts for compliance audit (preferred): { "receipt_status": "RECEIPT_ABSENT", "types": ["CARD"], "min_amount": 1000 }

Example 7: Expenses requiring review for flights / lodging: { "require_review_reasons": ["FLIGHTS", "LODGING"] }

Example 8: Expenses pending my approval: { "pending_approvals": ["FROM_ME"] }

Example 9: Reimbursements paid outside of Brex: { "types": ["REIMBURSEMENT"], "reimbursement_payment_method": "TRACKING" }

Example 10: Expenses with a government official attendee: { "government_attendees_status": "GOVERNMENT_OFFICIAL_PRESENT" }

Example 11: Expenses for a specific department (resolve name → ID with list_departments first): { "department_ids": ["cudmnt_eng123"] }

Example 12: Expenses for a specific merchant: { "merchant_ids": ["mrch_starbucks"] }

Example 13: Expenses by posted date (accounting): { "posted_at_start": "2025-04-01T00:00:00.000Z", "posted_at_end": "2025-04-30T23:59:59.999Z" }

Example 12: Get expenses with full receipt details including line items: { "expense_owner": "ME", "expand": ["RECEIPTS"] }

List all available GL accounts for the active accounting integration.

This tool executes a 3-step process: 1. Get the active accounting integration ID 2. Use the integration ID to get the extended field ID for GL accounts 3. Use the extended field ID to get all GL account options

Returns an object containing:

• accounts: Array of GL accounts
• glAccountField: The extended field definition for GL accounts
• gl_account_type: Nullable GL account type on each account when the ERP provides it

Returns null if no active integration is found.

Example response: { "glAccountField": { "id": "extended_field_cm9vkatzo0b8e0i36rxhz7z4r", "key": "user_category_int_cm9vkas3n00zx0e00zsk25h7z", "name": "GL Account", "status": "ACTIVE" }, "accounts": [ { "id": "efo_cm9vkauq30b9h0i36k2r3p66f", "identifier": "1328446901", "value": "1010 Cash", "status": "ACTIVE", "gl_account_type": "ASSET" }, { "id": "efo_cm9vkauq30b9i0i36pkb9lzan", "identifier": "-1076004205", "value": "1020 Accounts Receivable", "status": "ACTIVE", "gl_account_type": null } ] }

List legal entities (id + display name). Deleted entities are excluded.

REQUIRED prerequisite for the list_users entity filter: list_users only accepts legal entity IDs, so whenever the user mentions a legal entity by name (e.g. "Brex Inc.", "Brex UK Ltd."), call this tool first and pass the returned id into list_users.

Parameters: limit (1-200, default 25), cursor (pagination), search_text (narrow by display name).

Example Output: { "items": [{ "id": "le_1234", "name": "Brex Inc." }], "next_cursor": "cursor_abc" }

List locations (id + name). Deleted locations are excluded.

REQUIRED prerequisite for the list_users location filter: list_users only accepts location IDs, so whenever the user mentions a location by name (e.g. "San Francisco", "New York"), call this tool first and pass the returned id into list_users.

Parameters: limit (1-200, default 25), cursor (pagination), search_text (narrow by name).

Example Output: { "items": [{ "id": "culoc_1234", "name": "San Francisco" }], "next_cursor": "cursor_abc" }

List merchant categories (e.g., Restaurants, Software, Travel). Used to resolve a category name to its ID so that list_expenses can filter by merchant_category_ids.

Parameters:

• query: Optional similarity search on category name.
• limit: Page size (default 25, max 100).
• cursor: Pagination cursor from a previous call.

Example — find Restaurants category: { "query": "restaurant" }

Response (trimmed): { "items": [{ "id": "mccat_abc", "name": "Restaurants" }], "next_cursor": null }

Search card merchants by name. Used to resolve a merchant name to its ID so that list_expenses can filter by merchant_ids.

Parameters:

• query: Name substring to search for. Empty string returns popular/recent merchants.
• limit: Page size (default 25, max 100). Note: this endpoint does not support cursor pagination.

Example — find Starbucks: { "query": "starbucks" }

Response (trimmed): { "items": [{ "id": "mrch_abc", "name": "Starbucks" }], "next_cursor": null }

List cards belonging to the calling user. You can filter by status views (ACTIVE, EXPIRED, LOCKED, TERMINATED, WAITING_ACTIVATION). Results are paginated - use limit and cursor for pagination.

Example 1: Getting all my active cards: { "status": ["ACTIVE"] }

Example 2: Getting all my cards (any status): {}

Example 3: Getting my active and locked cards: { "status": ["ACTIVE", "LOCKED"] }

List expenses with filters. expense types (BILLPAY, CARD, CLAWBACK, REIMBURSEMENT),

Date Filtering (only one type can be used at a time):

• Purchase Date: purchased_at_start/purchased_at_end
• Filter by when expense was purchased. Date must be in UTC timezone.
• Posted Date: posted_at_start/posted_at_end
• Filter by when expense was posted. Date must be in UTC timezone.
• Reimbursement Submission Date: reimbursement_submitted_at_start/reimbursement_submitted_at_end
• Filter by when reimbursement was submitted (only works with REIMBURSEMENT type). Date must be in UTC timezone.

Amount Filtering (all amounts in USD):

• min_amount: Filter expenses with amount greater than or equal to this value (in USD, supports decimals with up to 2 places)
• max_amount: Filter expenses with amount less than or equal to this value (in USD, supports decimals with up to 2 places)

Text Search:

• search: Search expenses by merchant name, memo, or other text fields (e.g., "nike", "lunch")

Limit Filtering:

• limit_ids: Filter expenses by spend limit IDs (e.g., ["limit_123", "limit_456"])

Additional Fields:

• additional_fields: Array of optional fields to include in response. Supported values:
• "TRAVEL_METADATA"
• Includes flight, car rental, lodging, and train travel data
• "LOCATION"
• Includes expense location details (country, city, coordinates, etc.)

Understanding Expense Lifecycle and Compliance Status:

Expense Lifecycle: 1. New expense created (card transaction or reimbursement submitted) 2. Documentation phase: System checks if documentation is required (receipts, memo, attendees, etc.) 3. Spender submits documentation if needed 4. Review phase: System checks if approval/review is required based on company policy 5. Reviewer reviews and approves/rejects if necessary 6. Expense is finalized

Each expense returns TWO sets of compliance-related fields:

A. DOCUMENTATION COMPLIANCE (for spenders - receipts, memo, attendees):

• documentationComplianceStatus: Status of documentation requirements that the spender must fulfill
• "NOT_REQUIRED"
• Company policy does not require any documentation for this expense. Empty receipts/memo are acceptable.
• "COMPLETED"
• All required documentation has been provided according to policy.
• "DUE"
• Documentation is required by policy but not yet provided. Check missingDocumentations field for specifics.
• "OVERDUE"
• Required documentation is past its submission deadline. Check missingDocumentations field for specifics.
• missingDocumentations: Array of specific items required by policy but not yet provided. Possible values: ["MEMO", "RECEIPT", "ATTENDEES", "EXTENDED_FIELD"]
• Empty array []
• Either no documentation is required OR all required documentation is complete
• Non-empty array
• Lists specific items that must be provided (e.g., ["MEMO", "RECEIPT"])
• documentationSubmissionDeadline: The UTC timestamp by which documentation must be submitted (only present if documentation is required)

B. REVIEW COMPLIANCE (for reviewers - approval/rejection):

• reviewComplianceStatus: Status of review/approval requirements that the reviewer must fulfill
• "NOT_REQUIRED"
• Company policy does not require review/approval for this expense.
• "COMPLETED"
• The expense has been reviewed and approved/rejected.
• "DUE"
• Review is required by policy but not yet completed.
• "OVERDUE"
• Required review is past its deadline.
• reviewDeadline: The UTC timestamp by which the review must be completed (only present if review is required)

KEY DISTINCTIONS:

• DocumentationComplianceStatus="NOT_REQUIRED" and missingDocumentations=[] → Documentation not required by company policy
• Empty receipts/memo with documentationComplianceStatus="DUE" or "OVERDUE" and missingDocumentations=["RECEIPT","MEMO"] → Documentation IS required by policy but missing
• reviewComplianceStatus="DUE" or "OVERDUE" → Expense is waiting for someone to review/approve it
• reviewComplianceStatus="NOT_REQUIRED" → No approval needed

All dates should be in ISO 8601 format (e.g., "2025-04-01T07:00:00.000Z"). Date must be in UTC timezone. All amounts are assumed to be in USD currency. Results are paginated - use limit and cursor for pagination.

Example 1: Getting all my reimbursements: { "types": ["REIMBURSEMENT"], }

Example 2: Getting all card expenses purchased in April 2025 (UTC timezone): { "types": ["CARD"], "purchased_at_start": "2025-04-01T00:00:00.000Z", "purchased_at_end": "2025-04-30T23:59:59.999Z" }

Example 3: Getting reimbursements for transactions after a specific date (UTC timezone): { "types": ["REIMBURSEMENT"], "purchased_at_start": "2025-04-01T07:00:00.000Z" }

Example 4: Getting my expenses that are missing compliance documentation (e.g. receipts, memo): { "missing_compliance_documentation": true }

Example 5: Getting expenses between $100 and $500: { "min_amount": 120.78, "max_amount": 500.00 }

Example 6: Search for Nike expenses: { "search": "nike" }

Example 7: Getting expenses for a specific limit: { "limit_ids": ["limit_123"] }

Example 8: Getting expenses with travel metadata and location data: { "types": ["CARD"], "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Get all spend limits that apply to the current user with pagination support.

TERMINOLOGY: On Brex, these are called "limits" — NOT "budgets." There are two kinds: card limits (built into a card) and spend limits (exist independently). "Budget" is a separate Premium-only planning/tracking feature. When users say "budget" they almost always mean "limit." Prefer "limit" in responses unless the user is specifically asking about the Budget feature. The API returns fields named "budget_*" but these should be presented as "limits" to users.

Use this tool when:

• The user asks about "my limits" or "my spending limits" or "my budget"
• The user references a limit by name (e.g., "my Tony Report's T&E limit") - limit names may contain user names but refer to the limit, not the user
• You need to find a limit ID to use in other tools
• The user asks policy questions (e.g., "Can I expense Uber Eats?", "What's the approval policy?", "Do I need approval for X?", "What's the company travel policy?")

→ Call this tool FIRST to get limit IDs, then call get_expense_policy with the limit ID to answer the policy question → Policy information is ONLY available through get_expense_policy, which requires a limit ID from this tool

DO NOT use list_users_by_name_or_email when the user is asking about their own limits, even if the limit name contains a person's name. DO NOT ask for clarification about which limit when the user asks policy questions - be proactive: call list_my_limits first, and if there's only one limit, use it. DO NOT respond with general policy information or ask which policy the user wants - all policy data comes from get_expense_policy after getting limit IDs from this tool.

This includes:

• User Limit: The personal spending limit for the user
• Spend Limits: Shared spend limits where the user is a member

Each limit shows:

• Limit amount and remaining balance
• Period type (MONTHLY, QUARTERLY, etc.)
• Status (ACTIVE, EXPIRED, etc.)
• Start and end dates
• Amount spent in current period

Pagination:

• Use 'limit' parameter to specify how many spend limits to return (default: 100, max: 1000)
• Use 'cursor' parameter to paginate through results (use next_cursor from previous response)

SCENARIO-BASED EXAMPLES:

Example 1: Get all my limits (default - returns up to 100 limits): {}

Example 2: Get first 10 limits (useful for large accounts): { "limit": 10 }

Example 3: Get next page of limits: { "limit": 10, "cursor": "eyJhZnRlciI6IjEwIn0=" }

TOOL CHAINING WORKFLOWS:

Scenario 1: "How much is left on my Marketing Q1 limit?" → Call list_my_limits with {} to get all limits → Find limit where name="Marketing Q1", extract ID (e.g., "spl_abc123") → Present the available balance from the "available" field

Scenario 2: "Show me all expenses on my Travel & Entertainment limit" → Call list_my_limits with {} to get all limits → Find limit where name contains "Travel", extract ID (e.g., "spl_xyz789") → Call list_my_expenses with: { "limit_ids": ["spl_xyz789"] }

Scenario 3: "Can I expense Uber Eats on my company card?" (policy question) → Call list_my_limits with {} to get all limits → If user has only one active limit, extract its ID (e.g., "spl_policy123") → Call get_expense_policy with: { "spend_limit_id": "spl_policy123" } → Check policy rules for Uber Eats / Food Delivery merchant restrictions

Scenario 4: "Do I need approval for a $200 dinner?" → Call list_my_limits with {} to get limit IDs → Extract relevant limit ID (e.g., "spl_corp456") → Call get_expense_policy with: { "spend_limit_id": "spl_corp456" } → Check policy rules for approval thresholds on meal expenses

Scenario 5: "What did I spend on my Q1 Marketing limit last month?" → Call list_my_limits with {} to find "Q1 Marketing" limit → Extract limit ID (e.g., "spl_mkt789") → Call list_my_expenses with: { "limit_ids": ["spl_mkt789"], "purchased_at_start": "2025-03-01T00:00:00.000Z", "purchased_at_end": "2025-03-31T23:59:59.999Z" }

Scenario 6: "What are the rules for my Travel limit?" → Call list_my_limits with {} to find "Travel" limit → Extract the Travel limit ID (e.g., "spl_travel101") → Call get_expense_policy with: { "spend_limit_id": "spl_travel101" } → Present the complete policy rules from the response

List Brex account roles.

REQUIRED prerequisite for the list_users role and access filters: list_users only accepts role IDs, so whenever the user mentions a role or access type by name (e.g. "card admin", "employee", "bill pay approver", "card access"), call this tool first and pass the returned id into list_users.

Roles have two types:

• FUNCTIONAL ("what the user is" — CARD_ADMIN, EMPLOYEE, ACCOUNT_ADMIN, ...).

These IDs feed the list_users role filter.

• ACCESS ("what the user can do" — card access, bill pay approver, travel admin, ...).

These IDs feed the list_users access filter.

Pass role_type=["FUNCTIONAL"] to resolve names for the role filter, role_type=["ACCESS"] to resolve names for the access filter, or omit to return both. For FUNCTIONAL roles, is_admin=true indicates the role grants admin-level access.

Parameters: limit (1-200, default 100), cursor (pagination), role_type (filter by type).

Example Output: { "items": [ { "id": "role_1234", "name": "CARD_ADMIN", "display_name": "Card Admin", "role_type": "FUNCTIONAL", "is_admin": true } ], "next_cursor": null }

List employee titles (id + display title).

REQUIRED prerequisite for the list_users title filter: list_users only accepts title IDs, so whenever the user mentions a title by name (e.g. "Software Engineer", "Product Manager"), call this tool first and pass the returned id into list_users.

Parameters: limit (1-200, default 25), cursor (pagination), search_text (narrow by title name).

Example Output: { "items": [{ "id": "ti_1234", "name": "Software Engineer" }], "next_cursor": "cursor_abc" }

List travel trips across the company with filtering, sorting, and pagination.

Mirrors the Trips page on the Brex dashboard (Travel → Company → Trips). Use this tool when the user asks for a company-wide view of trips (e.g. "show all pending trips", "trips booked for Jane next month").

Filters are grouped to match the dashboard:

General:

• trip_statuses: Trip status. Array of trip statuses to include (e.g. ["UPCOMING", "PENDING"]). When omitted, trips in DRAFT, DELETED, or VOIDED states are excluded by default. To surface those, set trip_statuses explicitly.
• policy_status: Policy status. Filter by policy compliance across a trip's bookings (IN_POLICY, ANY_OUT_OF_POLICY, ALL_OUT_OF_POLICY). Trips without bookings are excluded when this is set.

Payment:

• spend_limit_ids: Spend limit. Array of spend-limit IDs to filter trips by the associated spend limit.

Date:

• billable_at_on_or_after / billable_at_on_or_before: Billable at. ISO-8601 timestamps bounding the trip's billable-at time.
• start_date_on_or_after / start_date_on_or_before: Start date. Date (YYYY-MM-DD) bounding the trip start date.

People:

• booker_scope: ALL_USERS, SELECTED_USERS, or SELF. Defaults to SELF on the GraphQL layer when omitted.
• booker_user_ids: Booker. Array of booker (employee) user IDs (cuuser_*). Required when booker_scope is SELECTED_USERS.
• traveler_user_ids: Traveler. Array of traveler user IDs (cuuser_*) for employees to filter by traveler.
• traveler_guest_emails: Traveler. Array of guest traveler emails.
• traveler_types: Traveler type. Array of ["EMPLOYEE", "GUEST"] to narrow by traveler type.

Sorting:

• order_field: Field to sort by (START_DATE, BILLABLE_AT, INSERTED_AT).
• order_direction: ASCENDING or DESCENDING. Defaults to DESCENDING.

Pagination:

• limit: Page size (default 25).
• cursor: Cursor from a previous response's next_cursor.

Example: { "trip_statuses": ["UPCOMING", "PENDING"], "order_field": "START_DATE", "order_direction": "DESCENDING", "limit": 25 }

List users with optional filtering and pagination.

ℹ️ Response narrowing for non-admin callers: callers without the user.list operation permission receive the same users, but with email, phone_number, location_id, and location_name omitted. Names, titles, departments, managers, roles, and status are always returned. Use this tool freely for discovery (e.g. picking attendees); fall back to get_user_myself when the caller needs their own contact info.

🚨 CRITICAL — ID filters REQUIRE companion discovery tools FIRST 🚨

The following filters accept ONLY Brex resource IDs (never names, labels, or human-readable strings). If the user describes a filter in plain English (e.g. "Engineering department", "San Francisco office", "Brex Inc. entity", "Software Engineer title", "R&D cost center", "bill pay approvers", "card admins", "reports to Jane Smith"), you MUST call the matching discovery tool first to resolve that string into an ID, then pass the ID here. DO NOT guess IDs. DO NOT pass the human-readable name directly. DO NOT silently drop the filter — always resolve it.

Filter → required discovery tool (ALWAYS call the discovery tool first when the user gives you a name instead of an ID):

• department → list_departments (IDs look like cudmnt_...) • location → list_locations (IDs look like culoc_...) • cost_center → list_cost_centers (IDs look like cc_...) • entity → list_legal_entities (IDs look like le_...) • title → list_titles (IDs look like ti_...) • role → list_roles with role_type=["FUNCTIONAL"] (IDs look like role_... or aurl_...) • access → list_roles with role_type=["ACCESS"] (IDs look like role_... or aurl_...) • manager → list_users_by_name_or_email (IDs look like cuuser_...)

Decision rule: if the user says a NAME, call the discovery tool; pass only the returned ID(s) into list_users. If the user already supplied an ID with the expected prefix, skip discovery and pass it straight through.

✓ Pagination & sorting (no discovery needed):

• cursor: Pagination cursor returned from a previous response.
• limit: Number of users to return (1-1000, default: 100).
• direction / sort: Sort direction ("asc"/"desc") and field (FIRST_NAME, LAST_NAME, EMAIL, ...).

✓ Enum filters (values listed inline — no discovery tool needed):

• status: Array of UserStatus (INVITED, PENDING_ACTIVATION, ACTIVE, INACTIVE, DISABLED, ARCHIVED).

Defaults to [INVITED, PENDING_ACTIVATION, ACTIVE, INACTIVE] if omitted.

• admin_role: Single value of "ADMINS" | "NON_ADMINS" | "ALL".

⚠️ When combining filters (e.g. "active users in Finance"), you MUST still resolve every name-based filter via its discovery tool AND include all requested filters in the final list_users call. Never drop a filter just because another filter was already applied.

Example Input 1 (basic, with defaults): {}

Example Input 2 (filter by department and role — department and role were resolved via list_departments and list_roles first): { "department": ["cudmnt_1234"], "role": ["role_5678"], "status": ["ACTIVE"] }

Example Input 3 (sort descending by last name, paginated): { "limit": 50, "direction": "desc", "sort": "LAST_NAME", "cursor": "cursor_1234" }

Example Output: { "items": [ { "id": "cuuser_123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE" } ], "next_cursor": "cursor_5678" }

List users by name or email

This tool allows you to search for users by name or email. It will return a paginated list of up to 10 users that match the search criteria, sorted by first name. If you only have the name or email, you can use this tool to find the user ID and their full details.

Example Input 1 (search by name): { "search_text": "John Smith" }

Example Input 2 (search by email): { "search_text": "john.smith@example.com" }

Example Output: { "items": [ { "id": "cuuser_123", "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "role": "CARD_ADMIN", "status": "ACTIVE" } ], "next_cursor": "cursor_1234" }

Get all vendors for the current authenticated user. Results are paginated - use limit and cursor for pagination.

IMPORTANT: Always use search_text to filter results when users ask about specific vendors, categories, or contact information. This tool is designed for efficient searching and filtering.

Parameters:

• cursor: Pagination cursor for next page of results
• limit: Default 30 | Max 100
• search_text: Text to filter vendors by name
• status: Optional single vendor status to filter by (ACTIVE, DELETED, PENDING, DRAFT, DECLINED, or MERGED)
• If omitted: Returns only ACTIVE vendors (default backend behavior)
• If empty array []: Returns vendors of ALL statuses
• If specified: Returns only vendors with that single status
• NOTE: Only ONE status can be filtered at a time

Search capabilities:

• Text search: Searches vendor name, legal name, and business name fields (case-insensitive, partial matching)
• Status filtering: Filter by a single vendor status at a time
• Combined filtering: Use both search_text and status together for precise results

Example usage:

• "Show me all my vendors" (only ACTIVE by default):

{ "limit": 100 }

• "Show me ALL my vendors regardless of status":

{ "status": [], "limit": 100 }

• Search for a specific vendor by name across ALL statuses:

{ "search_text": "Acme", "status": [], "limit": 25 }

• Find active software vendors:

{ "search_text": "Software", "status": ["ACTIVE"], "limit": 100 }

• Search by business name (ACTIVE by default):

{ "search_text": "Corp", "limit": 10 }

Query Brex expense data using natural language for comprehensive financial and operational analytics

This tool provides access to advanced expense reporting and analytics powered by specialized data models. It allows you to ask questions about spending patterns, compliance issues, budget performance, and organizational metrics using natural language queries.

ADMIN ONLY: This tool is only accessible to account administrators.

Supported Analytics Capabilities

Financial Analysis

• Total spending analysis by time period, department, merchant, vendor, or category
• Spending trends, comparisons (month-over-month, year-over-year), and forecasting
• Top spenders, vendors, and merchants by spend volume
• Category-level analytics across 40+ expense categories (travel, software, meals, etc.)
• Transaction-level details with temporal analysis (daily, weekly, monthly, quarterly)
• Average transaction amounts, statistical outliers, and anomaly detection
• Multi-currency support: billing, original, budget, and purchased currency amounts
• Spending breakdowns by expense type (card, reimbursement, bill pay)

Compliance & Policy Monitoring

• Identify expenses missing receipts or memos
• Track policy violations and out-of-policy expenses
• Monitor expense approval workflows and pending reviews
• Audit manually approved transactions without documentation
• Receipt compliance tracking by card, user, or department
• Expense status tracking (APPROVED, SUBMITTED, OUT_OF_POLICY, DRAFT, CANCELED, SETTLED)

Budget & Spend Limit Management

• Track department budgets and identify overruns (by $ or %)
• Monitor spend limit utilization across organizational units
• Track spend limit utilization by team or employee (users often say "spend limit" when they mean "budget" and vice versa — both are covered here)
• Compare actual vs. budgeted spend by department or category
• Analyze budget performance over time
• Identify recently created or edited budgets/limits

Disputes & Repayments

• Disputed transaction analysis (clawbacks)
• Repayment and refund pattern tracking
• Dispute trends by employee, department, or time period
• Canceled expense tracking

Accounting & General Ledger

• Double-entry accounting journal records and reconciliation
• GL code mapping to expenses, vendors, and departments
• GL coding patterns and line item analysis
• Accrual tracking and transaction date analysis
• Audit trail support across accounting records

Legal Entity Analysis

• Spending patterns by legal entity and country
• Cross-entity comparisons of expense volumes and types
• Entity-level employee and department activity
• Multi-entity approval and compliance rates

Organizational Analytics

• Employee expense patterns and rankings (top spenders per department/category)
• Department-wise spending breakdowns and comparisons
• Manager-employee expense relationships and reporting hierarchies
• Location-based expense analysis
• User-level metrics including approval ratios and compliance rates

Vendor & Merchant Analysis

• Top vendors/merchants by spend volume or transaction count
• Vendor performance tracking and quarterly/monthly trends
• Identify recurring vs. one-time vendor relationships
• Categorize SaaS vs. non-SaaS vendor spend
• Maximum spend tracking per vendor

Card Management & Transaction Analysis

• Card inventory: active, terminated, suspended, virtual, physical
• Card issuance tracking and activation rates
• Card-level spending patterns and transaction volumes
• Card purpose analysis (travel, office, etc.)
• Cardholder administration and card lifecycle management
• Per-card receipt attachment and compliance rates

Operational Reporting

• Pending approval workflows and manager review queues
• Reimbursement tracking and payout status
• Disputed transactions by user or time period
• Transaction settlement status and payment processing
• Card vs. reimbursement expense comparisons

Available Data

The tool has access to 14 specialized analytical views:

• Spending Analysis: Core expense metrics, temporal trends, and multi-currency breakdowns across employees, departments, and categories
• Top Spenders: Employee-level spending rankings with approval rates, vendor counts, and expense type breakdowns
• Vendor Analysis: Vendor spending patterns, SaaS categorization, and merchant-category insights
• Card Transaction Analysis: Card-level transaction details, daily totals, and per-card spending metrics
• Card Spending Analysis: Financial analysis of card utilization, transaction volumes, and ROI by card type and purpose
• Card Management: Card inventory and lifecycle tracking — issuance, activation, termination, and cardholder administration
• Compliance and Approval: Policy adherence monitoring, approval workflows, receipt compliance, and audit support
• Budget Management: Budget performance tracking, spend limits, over-budget identification, and budget lifecycle management
• Budget Limit Increases: Limit increase approval patterns, permanent vs. temporary increases, and voiding analysis
• Budget User Associations: Budget membership analysis — owners, members, and employee-budget relationships
• Disputes and Repayments: Disputed transaction (clawback) analysis, repayment patterns, and refund tracking
• Accounting Journal: Double-entry accounting records, reconciliation, and audit trail analysis
• GL Coding Analysis: General Ledger code mapping to expenses, vendors, and departments
• Legal Entity Spending: Multi-entity and multi-country spending comparisons and organizational breakdowns

Expense Types Supported

• CARD: Corporate card transactions
• REIMBURSEMENT: Employee reimbursements
• BILLPAY: Vendor bill payments
• CLAWBACK: Reversed or recovered expenses

Example Queries

Financial Analytics

1. "What was our total spending on travel expenses in Q4 2025?" 2. "Show me the top 10 vendors by spend last month" 3. "How much did the Engineering department spend on software purchases?" 4. "Compare our card spending between December and January" 5. "What are the largest transactions over $10,000 this quarter?" 6. "Show me spending trends over the last 6 months" 7. "What's our average expense amount by category?"

Compliance & Policy

8. "Which employees have the most transactions missing receipts?" 9. "Show me all manually approved expenses without documentation" 10. "List expenses that are out of policy this month" 11. "What's our receipt compliance rate by department?"

Budget & Spend Limits

12. "Which departments are most over budget by percentage?" 13. "Show me budget utilization for all departments" 14. "What budgets were recently created or edited?" 15. "What's the spend limit utilization for the Engineering team?"

Organizational

16. "Who are the top 5 spenders in the Engineering department?" 17. "Show me employee expense patterns by manager" 18. "Which users have the most spend per merchant category?"

Vendor Analysis

19. "Show me all recurring SaaS vendor spend from highest to lowest" 20. "What are our top non-SaaS vendors by spend?" 21. "Compare vendor spend quarter over quarter"

Operational

22. "Which managers have the most expenses pending their review?" 23. "Show me all disputed transactions this year by user" 24. "What's the status of pending reimbursements?"

Card Management

25. "How many active virtual cards do we have?" 26. "What's our card activation rate this quarter?" 27. "Show me spending by card purpose (travel vs. office)"

Disputes & Repayments

28. "Show me all disputed transactions this year by user" 29. "What's the trend in clawbacks over the past 6 months?"

Accounting & GL

30. "Show me GL code usage across departments" 31. "Which GL codes have the highest expense volumes?" 32. "List accounting journal entries for last month"

Legal Entity

33. "Compare spending across our legal entities" 34. "Which countries have the highest expense volumes?"

Example Input

{ "question": "What was our total spending on travel expenses in Q4 2025?" }

Example Output

{ "answer": "Your total spending on travel expenses in Q4 2025 was $125,450.32. Here's the breakdown by month: October: $38,200, November: $42,150, December: $45,100. The top categories were flights (45%), hotels (35%), and ground transportation (20%).", "metadata": { "toolCalls": [ { "name": "query_expenses", "input": {...}, "result": {...} } ] } }

Response Format

• answer (string): A natural language response to your question with the requested analytics
• metadata (object): Contains diagnostic information including:
• toolCalls: Array of internal tool calls made to generate the answer, useful for debugging

When to Use This Tool

✓ USE this tool for:

• Any aggregate analytics or reporting questions
• Compliance, policy, and audit queries
• Budget tracking and spend limit monitoring
• Top N rankings (top spenders, vendors, categories)
• Trend analysis and comparisons
• Statistical analysis (averages, outliers, anomalies)
• Operational reporting (pending reviews, approvals, disputes)
• Card inventory and lifecycle management questions
• Dispute and clawback analysis
• GL coding and accounting journal queries
• Legal entity and multi-country spending analysis
• Multi-dimensional analysis (department + category, user + time period)

✗ DO NOT use this tool for:

• Looking up a specific expense by ID (use get_expense_by_id instead)
• Fetching a user's own expenses (use list_expenses with expense_owner: "ME" instead)
• Fetching expenses for specific users by ID (use list_expenses with user_ids instead)
• Questions like "show me my expenses", "what did I spend on", "my recent transactions" — always use list_expenses for these
• Retrieving a specific card by ID (use get_card_by_id instead)
• Non-financial queries unrelated to expenses

Update attendees for a card expense. This tool allows you to update both external and internal attendees to any card expense.

Note: This tool will replace the existing attendees with the new attendees provided.

Parameters:

• card_expense_id: The ID of the card expense to add attendees to
• external_attendees: Array of external attendees (people outside the company with different email domains)
• internal_attendees: Array of internal attendee IDs (company employees by customer user ID)

Internal vs External Attendees:

• Internal attendees: Company employees with the SAME email domain as the current user (e.g., @acmecorp.com)

→ These require a user ID lookup using list_users_by_name_or_email

• External attendees: People from OTHER companies with DIFFERENT email domains (e.g., @vendorco.com)

→ These can be added directly with just their name, title, and company info (no user ID needed)

Example workflow

• Adding both internal and external attendees:

Scenario: Current user is bob.wilson@acmecorp.com adding a business dinner expense with:

• Jane Doe (jane.doe@acmecorp.com) - internal colleague (SAME @acmecorp.com domain)
• John Smith (john.smith@vendorco.com) - external vendor (DIFFERENT @vendorco.com domain)

Step 1: Identify which attendees are internal vs external by comparing email domains

• Current user: bob.wilson@acmecorp.com
• jane.doe@acmecorp.com → SAME @acmecorp.com domain → internal attendee → needs user ID lookup
• john.smith@vendorco.com → DIFFERENT @vendorco.com domain → external attendee → add directly

Step 2: Find the internal user ID using list_users_by_name_or_email Input to list_users_by_name_or_email: { "search_text": "jane.doe@acmecorp.com" }

Response from list_users_by_name_or_email: { "items": [ { "id": "user_456", "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@acmecorp.com", ... } ], "next_cursor": null }

Step 3: Add both internal and external attendees to the expense Input to replace_attendees_for_card_expense: { "card_expense_id": "card_exp_123", "external_attendees": [ { "name": "John Smith", "title": "Account Manager", "company_name": "VendorCo", "is_government_official": false } ], "internal_attendees": [ "user_456" ] }

Start an asynchronous expense download job. Returns a job ID immediately.

IMPORTANT: Download jobs can take up to 5 minutes to complete. Use get_expense_download_result with the returned job_id to poll for completion.

Recommended polling strategy:

• Poll 5s after starting
• If PROCESSING, wait 10 seconds and poll again
• Continue with 10-second intervals until COMPLETED or FAILED
• Maximum expected duration: 5 minutes

Parameters:

• start_date (required): Start of date range (ISO 8601, UTC)
• end_date (required): End of date range (ISO 8601, UTC)
• expense_types (optional): Filter by expense types: CARD, REIMBURSEMENT, BILLPAY, CLAWBACK
• statuses (optional): Filter by statuses: APPROVED, CANCELED, OUT_OF_POLICY, SETTLED, SUBMITTED
• user_ids (optional): Filter by specific user IDs
• min_amount (optional): Minimum expense amount (USD)
• max_amount (optional): Maximum expense amount (USD)

The CSV includes 15 columns: Parent ID, Flagged Expenses, Transaction Date, Expense Type, Card Last 4, Amount, Currency, Original Amount, Original Currency, Merchant Name, User, Budget Name, Memo, Expense Status, Payment Status.

IMPORTANT: This tool is only useful if your client environment can download files from URLs. The completed export provides a download URL for the CSV file. If you cannot download files (e.g., you are in a plain chat session without filesystem access), this tool will not help — use list_expenses with pagination instead.

When to prefer this over list_expenses:

• The dataset has 50+ expenses and the task involves aggregation, analysis, or bulk processing
• Your environment can download files AND run scripts to process the CSV locally (e.g., pandas, awk, shell commands)
• This avoids loading all expense data into the conversation context

If you are unsure whether you can download files from the returned URL, ask the user before starting the export.

Example: Start export for Q1 2025: { "start_date": "2025-01-01T00:00:00.000Z", "end_date": "2025-03-31T23:59:59.999Z" }

Submit feedback about the Brex API or MCP tools to the Brex product team on behalf of the user. This feedback is reviewed by the product team and used to prioritize improvements.

WHEN TO USE THIS TOOL:

• When a tool cannot fulfill the user's request due to missing functionality or unsupported filters.

Example: User asks to filter expenses by custom field, but list_expenses doesn't support that filter. -> submit_feedback with type "limitation" and describe the missing filter capability.

• When list or query tools return empty or unhelpful results for a reasonable request.

Example: User asks "show me spend by department last quarter" but no tool supports that aggregation. -> submit_feedback with type "limitation" describing the analytics gap.

• When the user explicitly asks to share a suggestion or report a problem with Brex tools.
• When a tool returns an error indicating a platform limitation (not a user input error).

Example: "This operation is not supported for this card type." -> submit_feedback with type "bug" including the error message and context.

• When accomplishing a task requires an unreasonably complex sequence of tool calls that could be simplified.

Example: Getting a budget summary requires 4 separate API calls that could be one. -> submit_feedback with type "suggestion" describing the desired simplified workflow.

WHEN NOT TO USE:

• Authentication or permission errors - help the user fix their token or scopes instead.
• Invalid input errors - help the user correct their input.
• Transient errors - retry the original tool first.
• The user has not expressed frustration or a gap - do not submit feedback proactively without cause.

IMPORTANT: Always inform the user before submitting feedback. Briefly explain what you're reporting and why.

Update memo for multiple expenses in bulk. All expenses will receive the same memo.

Parameters:

• expense_ids: Array of expense IDs to update
• memo: The memo text to apply to all expenses

Example (single expense): { "expense_ids": ["exp_123"], "memo": "Business lunch with client" }

Example (multiple expenses with same memo): { "expense_ids": ["exp_123", "exp_456", "exp_789"], "memo": "Q1 team building event" }

Upload receipts to a card expense by downloading them from provided URLs. This tool downloads receipts from the given URLs and uploads them to the specified card expense.

Parameters:

• expense_id: The ID of the card expense to attach the receipts to
• receipt_urls: Array of URLs where receipts can be downloaded (must be publicly accessible)

Example: { "expense_id": "card_exp_123", "receipt_urls": [ "https://example.com/receipts/lunch_receipt.jpg", "https://example.com/receipts/lunch_receipt_page2.pdf" ] }