search_grantsplus

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Natural language search query. Provide either query (single search) or queries (batch mode) — exactly one."
    },
    "queries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "BATCH MODE (paid, replaces batch_search_grantsplus): array of 2-5 search queries to run in parallel, dedupe, and merge. Example for clean energy: [\"renewable energy grants\", \"solar wind funding\", \"clean energy nonprofit\", \"sustainability grants\", \"green technology funding\"]. When set, query is ignored and the batch response params (detail_level, max_results, offset, max_response_tokens) apply."
    },
    "detail_level": {
      "type": "string",
      "enum": [
        "minimal",
        "compact",
        "full"
      ],
      "description": "Batch mode only: controls response verbosity (minimal/compact [default]/full). Ignored in single-query mode."
    },
    "max_results": {
      "type": "number",
      "minimum": 1,
      "description": "Batch mode only: maximum merged results to return (default 10). Ignored in single-query mode (use limit)."
    },
    "offset": {
      "type": "number",
      "minimum": 0,
      "description": "Batch mode only: number of merged results to skip for pagination (default 0). Ignored in single-query mode."
    },
    "max_response_tokens": {
      "type": "number",
      "minimum": 500,
      "description": "Batch mode only: token budget for the response (default 4000). Server auto-caps results to fit. Ignored in single-query mode."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "closed",
        "all"
      ],
      "description": "Filter by status"
    },
    "deadline_within_days": {
      "type": "number",
      "description": "Only opportunities closing within N days"
    },
    "posted_within_days": {
      "type": "number",
      "description": "Preferred alias for new_within_days: only opportunities WE ADDED (ingested) in the last N days. In queryless browse mode without a single source, the recency window is sampled across sources round-robin by ingest recency so one bulk harvester cannot own the digest; each source remains newest first. In windowCoverage, sourcesSampled counts distinct sources returned by the grouped provider query before MCP quality, judge, recency-withhold, and page filters; it is absent when no grouped sample was available, including when sampling was not attempted, and 0 means the grouped query succeeded but returned no sourced rows; sourcesServed counts distinct sources delivered on this page. windowCoverage.order is \"recency\" for the queryless browse digest or \"relevance\" when a query is present. windowIncomplete/incompleteReason is separate from ceilingTruncated, which is true only when the 2,000-row ceiling excluded records; ceilingTruncated and hardCeiling are present only when order is \"recency\" and are omitted entirely under \"relevance\" (query mode never walks past a single bounded fetch, so no ceiling logic runs). Uses the same ingest freshness field as newSince/recurring checks; not the opportunity posted date or deadline. If both posted_within_days and new_within_days are supplied, posted_within_days wins."
    },
    "new_within_days": {
      "type": "number",
      "description": "Backwards-compatible alias for posted_within_days. Only opportunities WE ADDED (ingested) in the last N days for recurring/delta checks (\"what is new since my last check\"). Additive to all other filters. In queryless browse mode without a single source, the recency window is sampled across sources round-robin by ingest recency so one bulk harvester cannot own the digest; each source remains newest first. The response includes newSince and windowCoverage: sourcesSampled counts distinct sources returned by the grouped provider query before MCP quality, judge, recency-withhold, and page filters; it is absent when no grouped sample was available, including when sampling was not attempted, and 0 means the grouped query succeeded but returned no sourced rows; sourcesServed counts distinct sources delivered on this page. windowCoverage.order is \"recency\" for the queryless browse digest or \"relevance\" when a query is present. windowIncomplete/incompleteReason is separate from ceilingTruncated, which is true only when the 2,000-row ceiling excluded records; ceilingTruncated and hardCeiling are present only when order is \"recency\" and are omitted entirely under \"relevance\" (query mode never walks past a single bounded fetch, so no ceiling logic runs). Not the opportunity posted date or deadline."
    },
    "since": {
      "type": "string",
      "description": "Stateless alternative to posted_within_days/new_within_days: ISO 8601 instant. Only opportunities ingested at/after this instant. Store the previous response newSince.newest and pass it here to manage your own watermark."
    },
    "organization": {
      "type": "string",
      "description": "Filter by funding organization"
    },
    "source": {
      "type": "string",
      "description": "Filter to a specific source/domain, e.g. \"grants.gov\", \"deq.nc.gov\", or \"sam.gov\"."
    },
    "limit": {
      "type": "number",
      "description": "Max results (default: 25)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from previous response"
    },
    "min_quality": {
      "type": "string",
      "enum": [
        "high",
        "medium",
        "low",
        "any"
      ],
      "description": "Minimum quality threshold (default: medium)"
    },
    "compact": {
      "type": "boolean",
      "description": "Return compact results (default: true). Set to false for full details."
    },
    "include_foundations": {
      "type": "boolean",
      "description": "Also search private foundations matching the query (default: true). Returns foundations that have historically funded similar work."
    },
    "user_context": {
      "type": "object",
      "properties": {
        "organization_type": {
          "type": "string",
          "enum": [
            "nonprofit",
            "startup",
            "small_business",
            "university",
            "government",
            "individual"
          ],
          "description": "Common natural-language phrasing (e.g. \"501(c)(3) nonprofit\") is also parsed; unparseable values are ignored with an explicit note in the response."
        },
        "location": {
          "type": "string"
        }
      },
      "description": "User context for better filtering"
    },
    "grants_filters": {
      "type": "object",
      "properties": {
        "agency_code": {
          "type": "string",
          "description": "Grants.gov agency code (HHS, DOE, NSF, etc.)"
        },
        "cfda": {
          "type": "string",
          "description": "CFDA/Assistance listing number (e.g., \"10.001\")"
        }
      },
      "description": "Grants.gov specific filters"
    }
  },
  "anyOf": [
    {
      "required": [
        "query"
      ]
    },
    {
      "required": [
        "queries"
      ]
    },
    {
      "required": [
        "source"
      ]
    },
    {
      "required": [
        "organization"
      ]
    }
  ]
}