How to Use the GrantLink AI Assistant

GrantLink Chat is an organization-scoped operations assistant. It can answer questions from GrantLink data, diagnose accounting and grant workflows, prepare exports and reports, and carry out supported changes under the same permissions and controls as the rest of the application.

Important: Chat is not an unrestricted database console, a live QuickBooks session, or a substitute for finance, legal, compliance, or program judgment. It can use only the context and tools available for the current conversation.

Before You Start

Confirm that:

• You are in the correct Clerk organization. Tool calls are scoped server-side to that organization.
• You are an organization member allowed to use Chat. The Viewer role is blocked from Chats and from server-side writes and actions.
• QuickBooks is connected and synced when the request depends on accounting data.
• You know whether you want an answer, a file, a report, or a GrantLink record change.
• You can review any financial, compliance, or externally shared result.

Chats are organization records, not private notes. Other authorized members of the same organization can load organization chat sessions and messages. Do not enter passwords, OAuth tokens, bank credentials, or unrelated personal data.

Open Chat

Start a general conversation

1. Open Chats in the main navigation.
2. Select New Chat.
3. Enter the goal, record scope, dates, and expected output.

Use a general chat for organization-wide questions, onboarding, diagnostics, exports, or work that is not already tied to one page.

Start with page context

On supported authenticated pages, select Ask GrantLink. The assistant receives the current route and available page context. On supported tables, selected grants or transactions can be added as an exact record set. On the grant budget, selected financial cells can carry their visible row and period context.

Page and selection context establishes the subject of the request; it is not approval for a write. Chat reloads authoritative data before changing records.

Start a report

Open a grant, program, or funder, select Reports, then Create Report. The resulting new chat is scoped to exactly that entity. See Creating Reports with GrantLink Chat.

What Chat Can Read

Depending on the question and context, Chat has tools for:

• Organization profile, funders, programs, grants, and upcoming deadlines
• Grant budgets, actuals, mappings, snapshots, and variance diagnostics
• Allocations, uncategorized or unallocated transactions, and allocation diagnostics
• Fund receipts, funding-share classifications, and reporting cycles
• The latest QuickBooks data mirrored into GrantLink, including accounts, transactions, vendors, classes, income, cash flow, sync status, and grant-tracking diagnostics
• Saved report templates, prior report snapshots, report workspaces, and organization branding
• Uploaded documents and selected page records

Tool availability is contextual. Chat may expose only the relevant subset for a turn, and every record lookup remains organization-scoped.

QuickBooks boundary: Most Chat accounting reads use GrantLink's latest synced QuickBooks mirror, not a fresh live request to QuickBooks. Check sync status when freshness matters. Correct source-controlled accounting data in QuickBooks and sync it; do not ask Chat to disguise the discrepancy in GrantLink.

What Chat Can Produce

Chat can return:

• Answers and explanations grounded in tool results
• Budget, allocation, mapping, sync, and accounting diagnostics
• Excel or CSV download cards for supported exports
• A generated copy of a saved grant sponsor workbook
• Draft grant, program, or funder web reports on qualifying plans
• PDF snapshots of reviewed report workspaces
• Secure QuickBooks OAuth links when a human must connect the account
• Suggested next prompts grounded in the completed work

Exports, PDFs, and reports are generated outputs. Chat does not file them in a funder portal, sign a certification, request a draw, or record external acceptance.

What Chat Can Change

Supported writes use one of three contracts:

Change	What to expect
A bounded organization-profile edit, such as name, fiscal-year start month, timezone, or default indirect rate	Direct authenticated write with an audit record
A low-risk reversible operation that a tool classifies as ready	Chat may apply it in the same turn when the request is explicit
A sensitive budget, allocation, lifecycle, archive, mapping, sync, import, restore, or multi-record operation	An immutable preview followed by a separate approval turn

For a sensitive plan:

1. Chat shows the exact effects, warnings, and plan details.
2. Review the preview; no domain record has changed yet.
3. Approve or reject using the displayed controls or a clear standalone response.
4. If approved, Chat applies only the saved plan ID and returns the result.

Sensitive plans expire after 15 minutes and fail if their source state is stale. An approval from an earlier message, another chat, or a response that also asks for edits does not authorize the plan. If the preview changes, the replacement plan needs fresh approval.

Approval cards authorize the exact record change shown. They do not approve an AI-generated report, publish a report, authorize unspecified future work, or bypass the current user's permissions.

Writing Effective Prompts

Name:

• The record or exact selected scope
• Exact dates or period
• Whether to use period, inception-to-date, or both
• The decision, action, or file needed
• Important exclusions and source requirements

Less effective: "How much did we spend?"

More effective: "For the Youth Services grant, show allocated personnel spending from January 1 through March 31, 2026, compare it with the same budget periods, and identify uncategorized amounts. Return the answer in Chat; do not change anything."

Less effective: "Fix the budget."

More effective: "Diagnose why the Community Health grant's Q2 personnel actuals are not appearing in the correct budget line. Read the budget mappings and allocations, explain the owning source of the problem, and preview any needed change before applying it."

Follow up in the same chat when the next request depends on earlier tool results. For an existing report workspace, focused edit requests reuse that report. For a materially different entity or deliverable, start a new scoped chat to reduce ambiguity.

Attach Files

Use the attachment control in the Chat input for award documents, reporting instructions, approved narrative, images, PDFs, CSV files, and spreadsheets.

Current handling differs by file:

• Images and PDFs can be sent directly to Chat's work model.
• Other supported documents are represented by bounded extracted text when possible; extraction may be truncated or fail.
• In a grant-scoped chat, an Excel or CSV budget upload is ingested through the budget-import workflow. The model receives bounded metadata and provenance rather than arbitrary workbook cells or raw bytes.
• Uploaded files are saved in GrantLink storage, but they are not automatically attached to a grant record. A separate supported file-attachment operation is required.

Always compare extracted facts with the original file before using them for setup, compliance, or external reporting.

External Web and Image Tools

Chat can use bounded external tools when they are configured:

• Open a requested public web page, subject to network, redirect, size, and time limits
• Search Unsplash for optional report imagery
• Sync organization website and branding only through the supported organization workflow

These tools cannot fetch localhost, private-network addresses, arbitrary remote file hosts, authenticated funder portals, or information behind credentials. GrantLink Chat does not currently expose a general web-search tool; provide the exact public URL you want it to open. Image search may be unavailable when its provider is not configured. External content can be incomplete or wrong and must not override organization records or sponsor documents.

Model and Conversation Limits

GrantLink routes Chat through Vercel AI Gateway and can use a separate work model for file, report, and report-edit turns. Provider selection is an implementation detail and can change; do not rely on one model's behavior as a product guarantee.

The service applies bounded message, attachment, tool-step, rate, and usage limits. Long conversations can omit older context from a model call even though the persisted chat remains visible. Restate critical scope and constraints when a conversation becomes long, and verify the current tool result rather than relying on model memory.

The model can misunderstand a request, select the wrong available tool, make a calculation error, or produce fluent unsupported prose. GrantLink instructions prohibit fabrication, but that instruction is not a guarantee. Use the verification steps in Understanding AI-Generated Summaries.

Privacy and Security

• Chat requests and tools use the authenticated organization from the server, not an organization ID supplied by the model.
• Record reads and writes enforce organization ownership; viewers cannot use write or action paths.
• QuickBooks OAuth credentials are not returned as model-visible tool data.
• AI Gateway calls require providers eligible for prompt-training disallowance and zero-data retention; if no eligible configured route is available, Chat fails closed instead of silently choosing a weaker route.
• Organization chats are visible to other authorized organization members, not only the creator.
• GrantLink's current privacy, security, contract, and subprocessor documentation remains authoritative for retention and data handling.

For board and vendor-review language, see AI, Security, and Vendor Risk FAQ for Boards.