HelpYouSponsor

Use this first when an authenticated Gratona admin asks what fundraising analysis Gratona can do, what questions are possible, what metrics, reports, donor segments, data-quality checks, codebook labels, saved filters, saved reports, groupings, or limitations are supported, or what to analyze next. This capability-discovery tool returns supported analysis surfaces and the correct next tools; it does not return live dashboard totals. Do not call dashboard, report, saved-filter, form, program, donor-list, or donation-summary tools before this for capability-discovery prompts.

hys_capabilities

Use this when an authenticated Gratona admin needs human-readable labels for donation methods, donation types, transaction statuses, designations, programs, or forms so answers do not expose raw codes or unlabeled internal IDs. When another Gratona tool returns program, form, or designation IDs, pass those exact IDs in ids so labels are complete even in large Gratona workspaces.

hys_codebook

Use this when an authenticated Gratona admin needs to confirm their connected Gratona workspace, current user, granted scopes, and enabled read surfaces. If the admin asks what fundraising analysis Gratona can do, what questions are possible, or what metrics, segments, reports, or groupings are supported, use hys_capabilities next before dashboard, program, form, or saved-filter tools. In admin-facing text, use only organization, Gratona workspace, or our data for the data boundary; avoid internal architecture labels.

hys_system_context

Use this to fetch the Gratona donor, recipient, or donation record identified by a search result id such as donor:123, entity:456, or donation:789. Results are limited to the authenticated admin's Gratona workspace and permission set.

hys_records_get

Use this when an authenticated Gratona admin asks for a concise daily admin brief, board-prep summary, or quick health check across their organization or Gratona workspace. Returns aggregate donor, recipient, sponsorship, donation, and watch-item signals without individual donor, gift, note, activity, or sponsorship rows. For precise current dashboard totals, date-bounded counts, or unusual live-count checks, use hys_dashboard_snapshot instead. Do not use this for broad capability-discovery questions about what fundraising analysis, metrics, segments, labels, groupings, reports, or next analyses Gratona can do; use hys_capabilities first. Use detail tools only after the admin asks who, which record, notes, or recent activity.

hys_dashboard_brief

Use this when an authenticated Gratona admin asks for actual current dashboard totals, a high-level snapshot, quick overview, or unusual live-count check across their Gratona workspace: donors, recipients, sponsorships, and donations. Do not use this for capability-discovery questions such as what fundraising analysis Gratona can do, what questions are possible, what metrics, donor segments, reports, labels, or groupings are supported, or what to analyze next; use hys_capabilities first for those. In admin-facing text, call this their organization or Gratona workspace and avoid internal architecture labels. Avoid listing individual donor, gift, or sponsorship rows unless the admin explicitly asks who or which records.

hys_dashboard_snapshot

Use this when an authenticated Gratona admin needs permitted activity history and full activity metadata from their organization or Gratona workspace. In admin-facing text, call the scope their organization or Gratona workspace. A record is resolved only when its ID was stated by the admin or returned by a Gratona tool in this same conversation. Never use a record from assistant memory, another conversation, examples, recent app activity, or a fallback/default. Use workspace-wide activity only when the admin explicitly asks for organization/workspace activity, a timeframe, or a specific activity type. If the admin only asks to check activity or show recent activity without a donor, recipient, record, timeframe, organization/workspace scope, or activity type, answer directly with one short follow-up question before calling this tool, such as "Which donor, recipient, or timeframe should I use?" Do not create a plan or call this tool first. If the admin uses an ambiguous pronoun such as their, that donor, or that recipient without a resolved donor, recipient, record, or timeframe, answer directly with one short follow-up question before calling this tool, such as "Which donor or recipient should I look up?" Do not create a plan or call this tool first.

hys_activity_logs_list

Use this when an authenticated Gratona admin explicitly asks for individual donation records, who gave recently, donor names, donor emails, or a recent gift list from their Gratona workspace. For high-level snapshots, board prep, or "anything unusual" prompts, use hys_dashboard_snapshot and hys_donations_summary with recent_limit 0 instead. Include donor contact fields only for donor profiles covered by the admin's Gratona permission set.

hys_donations_list

Use this when an authenticated Gratona admin needs recent stewardship notes for one donor or recipient they are allowed to view in their organization or Gratona workspace. A record is resolved only when its ID was stated by the admin or returned by a Gratona tool in this same conversation. Never use a record from assistant memory, another conversation, examples, recent app activity, or a fallback/default. If the admin only asks to check notes, or uses an ambiguous pronoun such as their, that donor, or that recipient without a resolved donor or recipient, answer directly with one short follow-up question such as "Which donor or recipient should I look up?" instead of guessing, searching for the app/workspace name, creating a plan, or calling this tool.

hys_notes_list

Use this when an authenticated Gratona admin needs donor or recipient profile form definitions they can access, usually before field-specific donor or recipient filtering. Do not use this for exact donor data-quality count questions about usable mailing addresses, email, phone, or cleanup totals; use hys_donor_data_quality_summary first because it already counts normalized and mapped custom fields. Do not use this for broad capability-discovery questions about what fundraising analysis, metrics, segments, labels, groupings, or reports Gratona can do; use hys_capabilities first.

hys_forms_list

Use this when an authenticated Gratona admin needs to list the programs and campaigns they are allowed to see, or when a user gives a program/campaign name before asking for recipients, sponsorships, notes, activity, or reports. Resolve the program id here first, then pass that id to recipient/entity tools such as hys_entities_list. Do not use this for broad capability-discovery questions about what fundraising analysis, metrics, segments, or reports Gratona can do; use hys_capabilities first.

hys_programs_list

Use this when an authenticated Gratona admin needs to review saved views or saved report filters available to their permission set. Do not use this for broad capability-discovery questions about what fundraising analysis, metrics, segments, or reports Gratona can do; use hys_capabilities first.

hys_filters_list

Use this when an authenticated Gratona admin needs saved report definitions and schedule metadata they are permitted to view.

hys_reports_list

Use this when an authenticated Gratona admin wants to find a donor by name, email, phone, or searchable donor text and return a bounded donor snapshot in one read-only call. Use hys_donors_search for result lists and hys_donors_get when the donor id is already known. Do not treat app, connector, environment, or workspace labels such as Gratona as donor queries; ask which donor when the reference is ambiguous.

hys_donors_lookup

Use this when an authenticated Gratona admin asks who belongs in a donor segment, such as lapsed donors, addressable donors, donors in a state, donors over a giving threshold, monthly-giving prospects, or donors who gave in one period but not another. For lapsed donors, supply both gave_between for the complete previous calendar year and did_not_give_between from the start of the current calendar year through today; either filter alone is not a lapsed cohort. This performs server-side filtering and returns names, contactability, giving metrics, lifecycle flags, and next-action hints without paging through raw donor records.

hys_segment_query

Use this only after a real read-only Gratona data tool has already returned structuredContent that should be shown as a compact visual snapshot in a compatible app UI. First call the needed read-only Gratona tool, then pass that tool's structuredContent directly as this tool's arguments. Do not invent or reuse unstated data for this tool. Do not use this for broad capability-discovery questions about what fundraising analysis, metrics, segments, labels, groupings, or reports Gratona can do; use hys_capabilities first. This presentation-only tool does not fetch records or bypass the admin's Gratona permission set.

hys_snapshot_widget_render

Use this when an authenticated Gratona admin wants to find donors or recipients by name, email, or other searchable text. Use hys_records_get with a returned result id to inspect a full record. Do not treat app, connector, environment, or workspace labels such as Gratona as donor or recipient queries; ask which donor or recipient when the record reference is ambiguous.

search

Use this when an authenticated Gratona admin asks for donation totals, counts, averages, recent donation patterns, stewardship signals, or board/admin brief metrics for their Gratona workspace. For high-level briefs, board prep, snapshot, or "anything unusual" prompts, use aggregate summary fields and keep recent_limit at 0. Do not request recent rows for broad snapshots. For grouped fundraising analytics such as giving by payment method, top donors, monthly revenue, or designation totals, prefer hys_aggregate_query. Payment-method summary rows include method_label; present that label first and do not ask the admin to confirm Gratona method codes; use hys_codebook when a complete donation-method label glossary is needed. Only set recent_limit above 0 when the admin explicitly asks who gave, which individual gifts, donor names, donor emails, or a recent gift list. When recent rows are requested, include donor contact fields only for donor profiles covered by the admin's Gratona permission set.

hys_donations_summary

Use this when an authenticated Gratona admin asks for sponsorship counts, sponsorship health, recent sponsorship patterns, board/admin brief metrics, or program-level sponsorship distribution for their Gratona workspace. For high-level briefs, board prep, snapshot, or "anything unusual" prompts, use aggregate summary fields and keep recent_limit at 0. Do not request recent rows for broad snapshots. Only set recent_limit above 0 when the admin explicitly asks who sponsors whom, which individual sponsorships, donor names, donor emails, or a recent sponsorship list. When recent rows are requested, include donor contact fields only for donor profiles covered by the admin's Gratona permission set.

hys_sponsorships_summary