# Search Federal Grant Programs

`Search_Federal_Grant_Programs` searches GovTribe's federal grant program dataset and returns ALN/CFDA-style program records with program identity, descriptive content, and sponsoring federal agency context.

## When To Use

* "Find grant programs by CFDA/ALN number, exact program name, or GovTribe ID."
* "Discover federal grant programs related to a mission topic or capability area."
* "List programs for one or more specific federal agencies."
* "Get top agencies by number of matching grant programs."
* "Return rollups only (`per_page: 0`) or rollups plus sample rows (`per_page > 0`)."

## Required Reading

1. [Search\_Mode\_And\_Query\_Guide](/user-guide/mcp/guides/search_mode_and_query_guide.md): Required before setting free-text query strings and choosing keyword vs semantic retrieval.

## Output Contract

* Top-level keys:
  * `data`: Array of result rows when `per_page > 0`.
  * `current_page`, `from`, `to`, `last_page`, `per_page`: pagination fields returned with row data.
  * `total`: Total matched row count for current query filters.
  * `path`: GovTribe search URL for this result set.
  * `contains`: Dataset label for the returned result set.
  * `search_results_id`, `search_results_id_can_generate_saved_search`, `view_search_results_url`: search-session metadata.
  * `aggregations`: Aggregation payload keyed by requested aggregation names when requested.
* Row keys:
  * `govtribe_id`
  * `govtribe_ai_summary`
  * `govtribe_type`
  * `govtribe_url`
  * `name`
  * `cfda_number`
  * `description`
  * `updated_at`
  * `federal_agency`
  * `federal_grant_awards`
  * `federal_grant_opportunities`
* Relationship retrieval map:
  * `federal_agency`
    * `resource_type`: `federal_agency`
    * `tool`: `Search_Federal_Agencies`
    * `filter`: `federal_agency_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_grant_awards`
    * `resource_type`: `federal_grant_award`
    * `tool`: `Search_Federal_Grant_Awards`
    * `filter`: `federal_grant_award_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`
  * `federal_grant_opportunities`
    * `resource_type`: `federal_grant_opportunity`
    * `tool`: `Search_Federal_Grant_Opportunities`
    * `filter`: `federal_grant_opportunity_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`

## Usage Patterns

Pattern A: Exact program lookup by CFDA/ALN-style identifier. Tool: `Search_Federal_Grant_Programs`

```json
{
  "query": "\"12.300\"",
  "search_mode": "keyword",
  "fields_to_return": [
    "govtribe_id"
  ],
  "per_page": 5,
  "page": 1
}
```

Pattern B: Semantic discovery of programs for a mission topic. Tool: `Search_Federal_Grant_Programs`

```json
{
  "query": "coastal resilience and climate adaptation community grants",
  "search_mode": "semantic",
  "fields_to_return": [
    "govtribe_id"
  ],
  "per_page": 10,
  "page": 1
}
```

Pattern C: Programs for a resolved agency ID (use `Search_Federal_Agencies` first if only a name is known). Tool: `Search_Federal_Grant_Programs`

```json
{
  "search_mode": "keyword",
  "fields_to_return": [
    "govtribe_id"
  ],
  "federal_agency_ids": [
    "7500|7529-A"
  ],
  "federal_agency_ids_operator": "in",
  "per_page": 10,
  "page": 1
}
```

Pattern D: Aggregation-only agency leaderboard for matching programs. Tool: `Search_Federal_Grant_Programs`

```json
{
  "search_mode": "keyword",
  "aggregations": [
    "top_federal_agencies_by_doc_count"
  ],
  "per_page": 0
}
```

Pattern E: Combined rows + aggregation output in one call. Tool: `Search_Federal_Grant_Programs`

```json
{
  "query": "behavioral health workforce training",
  "search_mode": "semantic",
  "fields_to_return": [
    "govtribe_id"
  ],
  "aggregations": [
    "top_federal_agencies_by_doc_count"
  ],
  "per_page": 5,
  "page": 1
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/tools/search-federal-grant-programs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.