Market Intelligence

# Federal Buying Pattern Analysis

## User Input
- **Target market slice:** [Buyer/customer dimension plus work dimension when available, or one resolved buying lane such as agency + NAICS, agency + work category, PSC, vehicle, IDV, or work category]

## Goal
Use GovTribe MCP tools to determine how a federal buyer, customer, or resolved federal buying lane actually buys a given type of contract work.

## Required Input
The user must provide a **target market slice** before analysis begins.

For this prompt, a **target market slice** means a federal buying lane defined by:
- a buyer or customer dimension when available, such as an agency, bureau, office, or buying organization
- a work dimension when available, such as a capability lane, work category, NAICS, PSC, vehicle, IDV, or contract seed used only to infer buying structure
- a fixed 24-month historical window

If both a buyer/customer dimension and a work dimension are provided, treat them together as one combined slice.
If only one dimension is provided, resolve that dimension and explicitly state what the resulting slice became.

Accept any of the following:
- Buyer or customer dimension, such as an agency, bureau, office, or buying organization
- Work dimension, such as a capability area, market lane, NAICS, PSC, vehicle, or IDV
- Contract number only if it is being used as a seed to infer buying structure
- Plain-language description of the work category or buying lane

Optional constraints the user may provide:
- Known incumbent or vendor context only if it sharpens the slice instead of turning the workflow into Vendor Deep Dive

Input rules:
- If the input resolves cleanly to one target market slice, proceed immediately.
- If the input is too vague to resolve to one market slice, ask for the minimum missing detail required to proceed.
- If a buyer/customer dimension and work dimension are both present, keep both in the slice definition.
- If only one dimension is present, explicitly state the resolved single-dimension slice in the output.
- Do not guess the target market slice.
- Do not start substantive analysis until the slice is resolved.

## Workflow

### Steps
1. Call `Documentation` once with `collections=["govtribe-for-agents"]`, `article_names=["Choose a search mode and write queries", "Manage search context", "Date filtering", "Filter by related records and hierarchies", "Aggregations and leaderboards", "Troubleshoot search results"]`, and `max_tokens=12000` before any other GovTribe tool.
   - Treat the returned guide articles as binding for search behavior, query construction, date filtering, relationship filters, aggregation-first review, search-context management, and troubleshooting used in this workflow.
   - Use the selected tool schema as the source of truth for tool-specific arguments, available fields, filters, sorts, aggregation keys, and response shapes.
2. If buyer, work, vendor-context, or record identifiers materially improve filtering, resolve and normalize the target market slice.
   - This workflow does not require a target company.
   - Resolve buyer or customer names into `federal_agency_ids` when names are provided.
   - Resolve work dimensions into `naics_category_ids` or `psc_category_ids` when codes or labels are provided.
   - Resolve a vehicle or IDV identifier into the correct GovTribe record when the user provides one directly.
   - If the user provides a contract number, vehicle, or IDV only as a seed, use it to infer the broader buying lane from the returned buyer, work-category, vehicle, IDV, and classification signals. Do not let the workflow collapse into a single-record deep dive unless the user explicitly scopes the question that narrowly.
   - If the user provides a known incumbent or vendor only as context for the market slice, use `Search_Vendors` to normalize identity, but do not let the workflow drift into Vendor Deep Dive.
   - Resolve agencies, NAICS, PSCs, vehicles, and IDVs only when that resolution materially sharpens the slice.
   - Express the final slice explicitly as buyer/customer dimension plus work dimension when both exist, or as the resolved single-dimension slice when only one exists.
   - Use a fixed `award_date_range` covering the last 24 months.
3. Run a historical award aggregation pass first.
   - Use `Search_Federal_Contract_Awards` as the primary evidence surface because market structure is best grounded in actual buying behavior.
   - Use `per_page: 0`.
   - Keep the scope filters stable across later comparison passes.
   - Preferred filters when available:
     - `contracting_federal_agency_ids`
     - `funding_federal_agency_ids`
     - `naics_category_ids`
     - `psc_category_ids`
     - `federal_contract_vehicle_ids`
     - `federal_contract_idv_ids`
     - `federal_contract_award_types`
     - `award_date_range`
   - Preferred aggregations:
     - `dollars_obligated_stats`
     - `top_awardees_by_dollars_obligated`
     - `top_contracting_federal_agencies_by_dollars_obligated`
     - `top_funding_federal_agencies_by_dollars_obligated`
     - `top_idvs_by_dollars_obligated`
     - `top_federal_contract_vehicles_by_dollars_obligated`
     - `top_set_aside_types_by_dollars_obligated`
     - `top_naics_codes_by_dollars_obligated`
     - `top_psc_codes_by_dollars_obligated`
   - Use this pass to estimate market size, measure concentration, identify set-aside posture, identify dominant agencies or offices, derive value-band behavior from returned dollars statistics, and determine whether vehicle concentration is strong enough to justify a dedicated vehicle or IDV branch.
4. Run a historical award row-retrieval pass after the aggregation pass.
   - Use `Search_Federal_Contract_Awards` again with the same stable scope filters.
   - Do not assume the first page is representative.
   - If the first page is dominated by very large outliers, weak lane matches, or records that are not representative of the resolved slice, rerun with a more representative sort, tighter resolved filters, or additional pagination before choosing example rows.
   - Request:
     - `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `award_date`, `completion_date`, `ultimate_completion_date`, `contract_type`, `descriptions`, `govtribe_ai_summary`, `dollars_obligated`, `ceiling_value`, `set_aside_type`, `awardee`, `parent_of_awardee`, `federal_contract_idv`, `federal_contract_vehicle`, `contracting_federal_agency`, `funding_federal_agency`, `naics_category`, `psc_category`, `place_of_performance`, `originating_federal_meta_opportunity_id`, `originating_federal_contract_opportunity`
   - Use these rows to pull representative examples, confirm whether the market is stand-alone or vehicle-linked, and support statements about structure, size, and repeat players.
5. Run the vehicle or IDV structure branch only when it materially improves correctness.
   - Only use this branch when one of these is true:
     - Award results show strong concentration in one or a few vehicles.
     - The single-award vs. multiple-award question cannot be answered credibly from award rows alone.
     - Vehicle, BPAs, GWACs, IDIQs, or stand-alone buying structure is central to the market characterization.
   - IDV path with `Search_Federal_Contract_IDVs`:
     - Use directly linked IDV IDs or an exact quoted contract number if needed.
     - Request:
       - `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `award_date`, `last_date_to_order`, `contract_type`, `pricing_type`, `description`, `govtribe_ai_summary`, `ceiling_value`, `set_aside`, `solicitation_procedures`, `extent_competed`, `legislative_mandate`, `multiple_or_single_award`, `awardee`, `parent_of_awardee`, `federal_contract_vehicle`, `contracting_federal_agency`, `funding_federal_agency`, `naics_category`, `psc_category`, `place_of_performance`, `task_orders`, `blanket_purchase_agreements`, `originating_federal_meta_opportunity_id`, `originating_federal_contract_opportunity`
     - Use this branch to support single-award vs. multiple-award interpretation, parent-vehicle structure, ordering behavior, and whether the lane primarily flows through IDVs.
   - Vehicle path with `Search_Federal_Contract_Vehicles`:
     - Use directly linked vehicle IDs or an exact quoted vehicle name if needed.
     - Request:
       - `govtribe_id`, `govtribe_url`, `name`, `award_date`, `last_date_to_order`, `contract_type`, `descriptions`, `govtribe_ai_summary`, `set_aside_type`, `shared_ceiling`, `originating_federal_meta_opportunity_id`, `originating_federal_contract_opportunity`, `federal_agency`, `federal_contract_awards`
     - Use this branch to support master-vehicle dependence, shared-ceiling structure, agency vehicle sponsorship, and whether the work is largely vehicle-routed or more stand-alone.
   - Do not run both branches unless the evidence requires both and the extra call materially improves correctness.
6. Use a current opportunity overlay only when present-tense buying posture or projection validation materially improves the answer.
   - Use `Search_Federal_Contract_Opportunities` only when one of these is true:
     - Historical awards alone do not explain whether the current market posture is persisting.
     - Current pipeline evidence materially sharpens present-tense buying posture.
     - Current pipeline evidence materially sharpens vehicle or set-aside interpretation.
     - Comparing historical buying behavior with live pipeline behavior materially improves the characterization.
   - If this branch runs, use `opportunity_types`-based passes rather than a loose mixed notice set:
     - Run a `Solicitation` pass when active demand matters.
     - Run a `Pre-Solicitation` pass when near-term demand matters.
     - Add `Special Notice` only when it materially sharpens structure or set-aside validation.
   - Use a concise keyword query only when it materially sharpens the resolved slice inside those typed passes.
   - Request:
     - `govtribe_id`, `govtribe_url`, `name`, `solicitation_number`, `opportunity_type`, `opportunity_state`, `part_of_mas`, `set_aside_type`, `posted_date`, `due_date`, `descriptions`, `govtribe_ai_summary`, `federal_meta_opportunity_id`, `federal_contract_vehicle`, `federal_agency`, `place_of_performance`, `naics_category`, `psc_category`, `points_of_contact`
   - Preferred aggregations when needed:
     - `top_federal_agencies_by_doc_count`
     - `top_set_aside_types_by_doc_count`
     - `top_naics_codes_by_doc_count`
     - `top_psc_codes_by_doc_count`
   - Use this branch only to validate whether the current market resembles the historical buying pattern, whether set-aside posture is tightening or loosening, and whether vehicle usage is persisting into the current pipeline.
   - Keep this live-demand overlay subordinate to the historical buying profile. Do not let a sparse, off-pattern, or empty live cohort override the core pattern derived from awards.
   - If this branch is thin or returns no usable demand, say so clearly rather than implying current demand exists.
7. Use a recent-vs.-prior trend comparison only when change over time materially improves the market characterization.
   - Only run this branch if trend, change over time, or projection validation is necessary to support the answer.
   - Default comparison window: the most recent 12 months versus the prior 12 months within the fixed 24-month window.
   - Rerun the same aggregation set for those two comparable windows unless the user provides a stronger reason to compare a different pair of windows.
   - Keep the same scope filters in both windows.
   - Compare set-aside mix, value band, buyer concentration, vehicle concentration, and dominant NAICS or PSC posture.
8. Classify the market explicitly using evidence-backed labels.
   - Buying model:
     - `Vehicle-Driven`
     - `Mixed`
     - `Standalone-Leaning`
   - Award structure:
     - `Single-Award-Leaning`
     - `Multiple-Award-Leaning`
     - `Unclear`
   - Set-aside posture:
     - `Mostly Unrestricted`
     - `Mixed Set-Aside`
     - `Small-Business Heavy`
   - Concentration:
     - `Highly Concentrated`
     - `Moderately Concentrated`
     - `Fragmented`
   - Do not assign these labels from a few isolated rows. The classification should follow the cleaned aggregation and representative-row evidence.
9. Exclude weak or misleading evidence explicitly.
   - Exclude keyword-adjacent awards outside the intended capability lane.
   - Exclude cross-lane contamination caused by loose NAICS or PSC overlap.
   - Exclude one-off outlier contracts treated as the whole market.
   - Exclude sparse current-opportunity evidence presented as a strong future projection.
   - Exclude vehicle assumptions not supported by returned fields.
   - Exclude grant or state and local interpretation in this contract-only workflow.
10. Perform a verification pass before finalizing the answer.
   - Remove obvious outliers or weak matches.
   - Confirm the main classification still holds after cleanup.
   - If trend claims are central, confirm they are based on comparable windows.
   - Lower confidence explicitly when the slice is sparse or the trend claim relies on thin evidence.
   - If evidence is too sparse to characterize the market credibly, say so clearly and stop.

## Output Format
Return the answer in this order:

1. **Federal Buying Pattern Summary**
   - Briefly explain how the market slice was interpreted.
   - Explicitly state the buyer/customer dimension, the work dimension, and the fixed last-24-month window used.
2. **Search Approach**
   - Briefly explain how the historical-award aggregation pass, row-retrieval pass, optional vehicle or IDV branch, optional current-opportunity overlay, and any trend comparison were used.
   - Briefly note the fixed 24-month window, the resolved buyer/work slice, and any narrowing decisions applied.
3. **Federal Buying Pattern Snapshot**
   - Use a required markdown table.
   - Recommended columns: `Dimension`, `Finding`, `Evidence`.
4. **Buying Pattern Findings**
   - Summarize the main buying model, award structure, set-aside posture, value-band pattern, buyer concentration, repeat-awardee pattern, and any contracting-versus-funding differences that matter.
5. **Vehicle / IDV Findings**
   - Include only when that branch was actually used.
6. **Current Opportunity Overlay**
   - Include only when that branch was actually used.
7. **Representative Records**
   - Use a compact markdown table.
   - Recommended columns: `Record`, `Agency`, `Vehicle / Structure`, `Set-Aside`, `Why It Matters`.
8. **Risks, Gaps, or Unknowns**
   - Briefly note sparse data, ambiguous structure, outlier sensitivity, or thin projection evidence.
9. **Overall Confidence**
   - State overall confidence and why.

### Optional charts
Use Mermaid only when aggregation evidence materially improves interpretation:
- `pie` for concentration or set-aside mix
- `xychart-beta` for recent-vs.-prior trend comparison

Fallback to compact markdown tables when the data is sparse.

## Citation Rules
- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.

## Grounding Rules
- Base claims only on provided context or GovTribe MCP tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or state that the goal cannot be fully completed from the available evidence.
- If a statement is an inference rather than a directly supported fact, label it as an inference.

# Find Early Federal Procurement Signals

## User Input
- **Target scope:** [Topic, capability, agency, GovTribe link, NAICS, PSC, or requirement area]

## Goal
Use GovTribe MCP tools to find early federal procurement signals across a market slice before they mature into fully active solicitations. Surface:
- Formal federal forecasts
- Early federal notices that function as demand signals
- Active federal solicitations that appear to belong to the same market slice
- Government-related news that corroborates or sharpens the procurement picture

## Required Input
The user must provide a target scope before analysis begins.

Accept any of the following:
- Topic, capability, or market lane
- Agency or customer
- NAICS or PSC
- GovTribe link to a related forecast or opportunity
- Plain-language description of the requirement area

Optional constraints the user may provide:
- Agency focus
- NAICS or PSC focus

Input rules:
- If the target scope is too vague to search well, ask for the minimum missing detail needed to proceed.
- Do not guess the target scope.
- Do not start substantive analysis until the target scope is resolved well enough to search.

## Workflow

### Steps
1. Call `Documentation` once with `collections=["govtribe-for-agents"]`, `article_names=["Choose a search mode and write queries", "Manage search context", "Date filtering", "Filter by related records and hierarchies", "Aggregations and leaderboards", "Find similar records", "Troubleshoot search results"]`, and `max_tokens=14000`.
    - Treat the returned guide articles as binding for search behavior, query construction, date filtering, relationship filters, aggregation-first review, similar-record retrieval, and troubleshooting used in this workflow.
    - Use the selected tool schema as the source of truth for tool-specific arguments, available fields, filters, sorts, aggregation keys, and response shapes.

2. If agency or classification resolution materially improves filtering, resolve and normalize the target scope.
    - This workflow does not require a target company.
    - Normalize topic or capability terms into a concise query set.
    - Resolve agencies into `federal_agency_ids` when names are provided.
    - Resolve NAICS into `naics_category_ids` when codes or labels are provided.
    - Resolve PSC into `psc_category_ids` when codes or labels are provided.
    - Translate the fixed 24-month lookback into:
        - `estimated_solicitation_release_date_range` for forecasts
        - `posted_date` for early-notice opportunity signals
        - `posted_date` plus a future-facing `due_date_range` for active solicitations

3. Run the forecast pass first.
    - Use `Search_Federal_Forecasts` as the first-class formal planning surface.
    - Use the default search behavior for aggregation-first and filter-first passes.
    - Aggregation-first pass:
        - Use `per_page: 0`
        - Use `aggregations` such as `top_federal_agencies_by_doc_count`, `top_set_aside_types_by_doc_count`, `top_naics_codes_by_doc_count`, and `top_contacts_by_doc_count`
        - Use this pass to size the forecast slice, identify dominant agencies and set-aside posture, and narrow the row-retrieval pass when the cohort is broad
    - Row-retrieval pass:
        - Request `govtribe_id`, `govtribe_url`, `name`, `forecast_type`, `set_aside`, `estimated_solicitation_release_date`, `estimated_award_start_date`, `estimated_award_value`, `descriptions`, `updated_at`, `federal_agency`, and `points_of_contact`
    - Use the tool’s documented field names exactly.
    - Important detail:
        - Use `estimated_solicitation_release_date_range` as the primary release-window filter for this radar
        - The returned row field for award timing remains `estimated_award_start_date`

4. Run the early-notice pass second.
    - Use `Search_Federal_Contract_Opportunities` as the early-notice surface.
    - Default early-signal opportunity types:
        - `Pre-Solicitation`
        - `Special Notice`
    - Start with the default search behavior.
    - Use exact quoted identifiers where possible.
    - For RFI, sources-sought, and market-research style asks, carry those terms in `query`.
    - Do not assume there is a dedicated `RFI` opportunity-type enum. Use `Special Notice` plus query terms when needed.
    - Keep the pass within the last 24 months using `posted_date`.
    - Request:
        - `govtribe_id`, `govtribe_url`, `name`, `solicitation_number`, `opportunity_type`, `opportunity_state`, `part_of_mas`, `set_aside_type`, `posted_date`, `due_date`, `descriptions`, `govtribe_ai_summary`, `federal_meta_opportunity_id`, `federal_contract_vehicle`, `federal_agency`, `naics_category`, `psc_category`, and `points_of_contact`

5. Run the active-solicitation pass third.
    - Use `Search_Federal_Contract_Opportunities` again with `opportunity_types` set to `Solicitation`.
    - Keep this pass within the same 24-month posted-date window.
    - Use a future-facing `due_date_range` so only active solicitations remain.
    - Start with the default search behavior.
    - Request:
        - `govtribe_id`, `govtribe_url`, `name`, `solicitation_number`, `opportunity_type`, `opportunity_state`, `part_of_mas`, `set_aside_type`, `posted_date`, `due_date`, `descriptions`, `govtribe_ai_summary`, `federal_meta_opportunity_id`, `federal_contract_vehicle`, `federal_agency`, `naics_category`, `psc_category`, and `points_of_contact`

6. Run the government-related news pass fourth.
    - Use `Search_Government_Related_News_Articles`.
    - Use `date_published` over the last 12 months.
    - Start keyword-first using the normalized topic, agency, NAICS, PSC, and any concrete requirement terms surfaced by the forecast and opportunity passes.
    - Request:
        - `govtribe_id`, `govtribe_url`, `title`, `subheader`, `published_date`, `site_name`, and `body`
    - Sort by `datePublished` descending for chronology-first review.
    - Exclude articles that do not materially relate to the scoped procurement topic, customer, or requirement area.
    - Treat news as corroborating context rather than stronger evidence than forecasts, notices, or solicitations.

7. Use one careful semantic follow-on only after the keyword/filter-first passes.
    - Before a generic semantic pass, prefer one stage-progression recovery pass when one stage is strong and another stage is unexpectedly thin.
    - If the forecast pass is strong but the early-notice or solicitation passes are thin, use `Search_Federal_Contract_Opportunities` with `similar_filter` from the strongest forecast and keep the strongest agency, NAICS, PSC, posted-date, due-date, and stage filters in place.
    - If the early-notice or solicitation passes are strong but forecasts are thin, use `Search_Federal_Forecasts` with `similar_filter` from the strongest notice or solicitation and keep the strongest agency, NAICS, PSC, and release-window filters in place.
    - Use this branch only to recover likely stage-adjacent procurement records and clarify progression.
    - Do not use `similar_filter` in the government-related news branch.
    - Only if the stage-progression branch is still too thin should you use a generic semantic pass.
    - Use `search_mode: "semantic"` on forecasts, opportunities, or government-related news only when the topic is conceptual or synonym-heavy.
    - Keep the strongest structural filters in place.
    - Use `_score` sorting for semantic passes.
    - Do not let semantic broadening replace stage-based filtering.
    - Do not let semantic news hits outweigh stronger procurement evidence.

8. Merge, dedupe, and stage the procurement signals.
    - Forecast records stay in the `Forecast` bucket.
    - Opportunity rows are mapped into `Pre-Solicitation` or `Special Notice / RFI / Sources Sought`.
    - `Solicitation` rows go into `Active Solicitation`.
    - News rows stay in the `Government-Related News` bucket.
    - Collapse obvious duplicates by agency, title, timing, and scope similarity.
    - If a formal forecast and an early notice appear to describe the same requirement, keep both and explain the progression.
    - If a formal forecast, early notice, and active solicitation appear to describe the same requirement, keep the stage progression explicit.
    - If a news article materially corroborates a forecast, early notice, or solicitation, keep both and explain the connection.

9. Use optional historical validation only when it sharpens the procurement signal set.
    - If the user asks whether a signal looks like a recompete or wants historical confirmation, use `Search_Federal_Contract_Awards`.
    - Validate through agency, NAICS, PSC, vehicle, and date context.
    - Use this only to sharpen the procurement signal set, not to turn the workflow into `Find Federal Recompete Opportunities`.

10. Rank and verify the remaining signals before finalizing the answer.
    - Use the signal labels and scoring factors in `## Output Format`.
    - Prefer records with concrete stage clarity, timing, scope specificity, agency clarity, and evidence of progression from forecast to notice to solicitation when applicable.
    - Use news to sharpen context, timing, or market relevance, but keep procurement records primary.
    - Remove weak signals before finalizing the procurement signal set.
    - If the evidence is sparse, conflicting, or mostly weak, say so clearly instead of forcing a confident radar.
    - Include timing outlook and next-step logic when the evidence supports it.

## Output Format
Use these signal labels:
- `High Signal`
- `Medium Signal`
- `Watch`
- `Weak`
- `Exclude`

Score each surfaced item using:
- Stage maturity
- Release timing
- Specificity of scope
- Agency clarity
- Set-aside clarity
- Classification clarity
- Presence of points of contact
- Evidence of progression from forecast to notice to solicitation

Return the answer in this order:

1. **Target Scope Summary**
    - Briefly summarize how the topic, agency, codes, and fixed 24-month window were interpreted

2. **Search Approach**
    - Briefly explain how the forecast pass, early-notice pass, active-solicitation pass, and government-related news pass were used
    - Briefly note any filters, time windows, or stage-scope decisions applied

3. **Forecast Signals**
    - List the strongest formal forecast signals

4. **Early Notice Signals**
    - List the strongest early-notice signals

5. **Active Solicitation Signals**
    - List the strongest active solicitation signals

6. **Government-Related News Signals**
    - List the strongest relevant recent articles that sharpen or corroborate the procurement picture
    - If no relevant recent news is found, say so clearly

7. **Procurement Signal Summary and Timing Outlook**
    - Summarize which signals look strongest and what stage progression appears most likely

8. **Risks, Gaps, or Unknowns**
    - Briefly note sparse signal coverage, ambiguity, thin evidence, or timing uncertainty

9. **Overall Confidence**
    - State overall confidence and why
    - Keep procurement evidence primary and treat news as corroborating context

## Citation Rules
- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.

## Grounding Rules
- Base claims only on provided context or GovTribe MCP tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or state that the goal cannot be fully completed from the available evidence.
- If a statement is an inference rather than a directly supported fact, label it as an inference.

# Find Federal Recompete Opportunities

## User Input
- **Target scope:** [Company, incumbent, agency, NAICS, PSC, contract or vehicle identifier, or work description]

## Goal
Use GovTribe MCP tools to identify federal awards, task orders, BPAs, IDIQs, and contract vehicles nearing meaningful lifecycle dates that may represent follow-on or recompete opportunities.

## Required Input
The user must provide a **target scope** before analysis begins.

Accept any of the following:
- Company or incumbent vendor name
- Agency, subagency, or buying office
- Product, service, or capability area
- NAICS, PSC, or other classification
- Contract, BPA, task order, IDIQ, or vehicle identifier
- Plain-language description of the work to search for

Optional constraints the user may provide:
- Agency or customer focus
- Contract type or vehicle type
- Incumbent vendor filters
- NAICS, PSC, or category filters

Input rules:
- If the target scope resolves cleanly enough to search, proceed immediately.
- If the target scope is too vague, ask for the minimum missing detail needed to proceed.

## Workflow

### Steps
1. Before any other GovTribe tool call, use `Documentation` once with `collections=["govtribe-for-agents"]`, `article_names=["Choose a search mode and write queries", "Manage search context", "Date filtering", "Filter by related records and hierarchies", "Aggregations and leaderboards", "Find similar records", "Troubleshoot search results"]`, and `max_tokens=14000`.
    - Treat the returned guide articles as binding for search behavior, query construction, lifecycle date filtering, relationship filters, aggregation-first sizing, similar-record retrieval, search-context management, and troubleshooting used in this workflow.
    - Use the selected tool schema as the source of truth for tool-specific arguments, available fields, filters, sorts, aggregation keys, and response shapes.

2. If identifiers or scoped filters materially improve filtering, resolve the target scope and reusable IDs before deeper search.
    - Use `Search_Vendors` when the user provides a company name, incumbent vendor, or GovTribe vendor link.
    - Use `Search_Federal_Agencies`, `Search_Naics_Categories`, and `Search_Psc_Categories` to resolve agency and classification filters.
    - For exact vendor names, identifiers, or known contract or vehicle numbers, use a double quoted `"query"`.
    - If the user provides a known contract, order, BPA, IDIQ, or vehicle identifier, resolve it with the most likely dataset first:
        - `Search_Federal_Contract_Awards` for definitive contracts, purchase orders, delivery orders, and BPA calls
        - `Search_Federal_Contract_IDVs` for vendor-specific BPAs, IDIQs, GWAC awards, schedules, BOAs, and similar parent instruments
        - `Search_Federal_Contract_Vehicles` for master vehicle names or acronyms
    - Use `fields_to_return` explicitly. At minimum request:
        - `Search_Vendors`: `govtribe_id`, `govtribe_url`, `name`, `uei`, `dba`, `business_types`, `sba_certifications`, `parent_or_child`, `parent`, `naics_category`, `federal_contract_awards`, `federal_contract_idvs`, `awarded_federal_contract_vehicle`, `govtribe_ai_summary`
    - Extract the strongest available scope signals:
        - Target company, agency, or market segment
        - Core product or service area
        - Relevant NAICS, PSC, or other classifications
        - Contract or vehicle type
        - Relevant keywords and synonyms
        - Known incumbent vendors, if any
        - Whether the resolved scope is broad enough to justify aggregation-only lifecycle sizing or narrow enough for direct row review

2A. Classify the resolved target scope as either a **seed record** or a **market scope**.
    - A **seed record** is a specific award, IDV, or vehicle that the user provided by identifier.
      It is the basis for the search, not a discovered recompete.
    - A **market scope** is a broader filter set such as a vendor, agency, NAICS, PSC, or work area
      where the expiring cohort itself is the discovery.
    - When the target scope resolves to a seed record:
        - Capture its key facts for use in Output Section 1, including incumbent, agency, lifecycle dates, scope summary, vehicle context, and material transaction history.
        - Use the seed to anchor downstream filters, similarity passes, and follow-on evidence gathering.
        - Do not include the seed record itself in Output Section 4 unless the user explicitly asked to evaluate that exact record as the output item.
        - Focus downstream search effort on follow-on evidence such as new solicitations, sources sought notices, forecasts, similar expiring awards from the same agency or program, or bridge and extension signals in transaction history.
    - When the target scope resolves to a market scope, proceed normally; expiring records discovered by the search are themselves the output.

3. Choose the lifecycle retrieval path after scope resolution.
    - **3A. Aggregation-only lifecycle sizing branch**
        - Run this branch only when one or more are true:
            - The user asks for market sizing, concentration, dominant awardees, vehicles, categories, or set-aside posture
            - The resolved scope is broad, such as an agency plus capability lane, agency plus NAICS or PSC slice, or an incumbent plus a broad work category
            - The initial scoped expiring cohort is likely too large or uncertain for efficient direct row review
        - Skip this branch when one or more are true:
            - The user provides an exact contract, order, BPA, IDIQ, or vehicle identifier and did not ask for market sizing around that seed
            - The search is clearly narrow, vendor-specific, or account-specific
            - The resolved cohort is obviously small enough for direct row review
        - Use `per_page: 0`.
        - Omit `fields_to_return` unless you also need rows.
        - Apply the same resolved filters that will define the later row cohort.
        - Keep aggregation calls focused on one market-sizing question when possible.
        - Use the top-level `total` as the full scoped expiring-population size for this branch.
        - Award aggregation path with `Search_Federal_Contract_Awards`:
            - Use `ultimate_completion_date_range` for the next 24 months and the strongest available `vendor_ids`, `contracting_federal_agency_ids`, `funding_federal_agency_ids`, `naics_category_ids`, `psc_category_ids`, `federal_contract_vehicle_ids`, `federal_contract_award_types`, and `set_aside_types`.
            - Use `aggregations` such as `dollars_obligated_stats`, `top_awardees_by_dollars_obligated`, `top_federal_contract_vehicles_by_dollars_obligated`, `top_set_aside_types_by_dollars_obligated`, `top_naics_codes_by_dollars_obligated`, and `top_psc_codes_by_dollars_obligated`.
        - IDV aggregation path with `Search_Federal_Contract_IDVs`:
            - Use `last_date_to_order_range` for the next 24 months and the strongest available `vendor_ids`, `contracting_federal_agency_ids`, `funding_federal_agency_ids`, `naics_category_ids`, `psc_category_ids`, `federal_contract_vehicle_ids`, `federal_contract_idv_types`, `multiple_or_single_award`, and `set_aside_types`.
            - Use `aggregations` such as `top_awardees_by_doc_count`, `top_vehicles_by_doc_count`, `top_set_aside_types_by_doc_count`, `top_naics_codes_by_doc_count`, and `top_psc_codes_by_doc_count`.
        - Use the aggregation results only to estimate the size of the scoped expiring segment, identify which awardees, vehicles, and categories dominate it, and decide whether the row-level pass should emphasize awards, IDVs, or both.
        - Do not treat aggregation results alone as evidence that a record is a likely recompete.
        - When using denominator-versus-numerator framing:
            - Treat the full scoped expiring cohort from this branch as the denominator
            - Treat the tighter likely-recompete cohort that survives later row-level screening as the numerator
            - Do not claim the ratio if cleanup or later filtering materially changes the scope
    - **3B. Row-level lifecycle retrieval branch**
        - Always run a row-level lifecycle retrieval pass.
        - If 3A was skipped because the scope is narrow, move directly to this branch.
        - Use keyword and structured filters before any semantic broadening.
        - Use `per_page` intentionally and paginate as needed when the cohort remains material.
        - If 3A ran, keep the same base filters so the row cohort matches the sized cohort.
        - Award path with `Search_Federal_Contract_Awards`:
            - Use `ultimate_completion_date_range` for the next 24 months of expiration or completion-horizon filtering.
            - Add the strongest available `vendor_ids`, `contracting_federal_agency_ids`, `funding_federal_agency_ids`, `naics_category_ids`, `psc_category_ids`, `federal_contract_vehicle_ids`, `federal_contract_award_types`, and `set_aside_types`.
            - Use `sort` with `completionDate` when completion timing should drive review order.
            - At minimum request `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `award_date`, `completion_date`, `ultimate_completion_date`, `contract_type`, `descriptions`, `govtribe_ai_summary`, `dollars_obligated`, `ceiling_value`, `set_aside_type`, `awardee`, `parent_of_awardee`, `federal_contract_idv`, `federal_contract_vehicle`, `contracting_federal_agency`, `funding_federal_agency`, `naics_category`, `psc_category`, `originating_federal_meta_opportunity_id`, and `originating_federal_contract_opportunity`.
        - IDV path with `Search_Federal_Contract_IDVs`:
            - Use `last_date_to_order_range` for the next 24 months of ordering-period expiration so expired or inactive parent instruments are excluded.
            - Add the strongest available `vendor_ids`, `contracting_federal_agency_ids`, `funding_federal_agency_ids`, `naics_category_ids`, `psc_category_ids`, `federal_contract_vehicle_ids`, `federal_contract_idv_types`, `multiple_or_single_award`, and `set_aside_types`.
            - Use `sort` with `lastDateToOrder` when ordering-window timing should drive review order.
            - At minimum request `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `award_date`, `last_date_to_order`, `contract_type`, `pricing_type`, `description`, `govtribe_ai_summary`, `ceiling_value`, `set_aside`, `solicitation_procedures`, `extent_competed`, `legislative_mandate`, `multiple_or_single_award`, `awardee`, `parent_of_awardee`, `federal_contract_vehicle`, `contracting_federal_agency`, `funding_federal_agency`, `naics_category`, `psc_category`, `blanket_purchase_agreements`, `task_orders`, `originating_federal_meta_opportunity_id`, and `originating_federal_contract_opportunity`.
        - Vehicle path with `Search_Federal_Contract_Vehicles`:
            - Use `last_date_to_order_range` for the next 24 months of master-vehicle ordering-period expiration so expired or inactive vehicles are excluded.
            - Add the strongest available `vendor_ids`, `funding_federal_agency_ids`, and `federal_contract_vehicle_types`.
            - Use `sort` with `lastDateToOrder` when ordering-window timing should drive review order.
            - At minimum request `govtribe_id`, `govtribe_url`, `name`, `award_date`, `last_date_to_order`, `contract_type`, `descriptions`, `govtribe_ai_summary`, `set_aside_type`, `shared_ceiling`, `federal_agency`, `federal_contract_awards`, `originating_federal_meta_opportunity_id`, and `originating_federal_contract_opportunity`.
        - Do not invent unsupported lifecycle filters such as a generic `option_end_date`. If option timing matters, treat it as inference only when the returned evidence supports that reading.

4. Broaden the search only after the keyword and filter-first row pass.
    - Semantic search is a broadening pass only. It must not replace the Step 3B row-level lifecycle retrieval branch.
    - If the search began from an exact award, IDV, or vehicle seed, or if the row-level lifecycle pass produced one strong candidate but the cohort is still too narrow, prefer one same-family `similar_filter` widening pass before a generic semantic pass.
    - Use seeded widening to find related follow-on evidence and same-family records around the seed, not to resurface the seed itself as a discovery.
    - Use `Search_Federal_Contract_Awards` for award seeds, `Search_Federal_Contract_IDVs` for IDV seeds, and `Search_Federal_Contract_Vehicles` for vehicle seeds.
    - Keep the same lifecycle window and the strongest agency, vendor, NAICS, PSC, type, and set-aside filters in place.
    - Do not use cross-dataset similarity jumps in this workflow.
    - Only if the seeded widening pass is still too thin should you use generic semantic broadening.
    - Use `Search_Federal_Contract_Awards`, `Search_Federal_Contract_IDVs`, or `Search_Federal_Contract_Vehicles` again with `search_mode: "semantic"`.
    - Build a concise plain-language `query` from the resolved scope, mission language, and domain synonyms.
    - Keep the strongest structured filters in place while broadening.
    - Use `_score`-based `sort` for semantic passes unless the user specifically needs date ordering instead.
    - Use `similar_filter` only if the current tool supports it and you have a strong seed record with the correct `govtribe_type` and `govtribe_id`.
    - Do not treat supporting transaction evidence as the primary semantic-search surface.

5. If awards, IDVs, or vehicles are identified and supporting modification evidence is needed, use `Search_Federal_Transactions`.
    - Use this only after awards, IDVs, or vehicles are identified.
    - Use the strongest available `federal_contract_award_ids`, `federal_contract_idv_ids`, `federal_contract_vehicle_ids`, `vendor_ids`, `contracting_federal_agency_ids`, `funding_federal_agency_ids`, `naics_category_ids`, and `psc_category_ids`.
    - Use `sort` with `transactionDate` descending when reviewing recent modification activity.
    - At minimum request `govtribe_id`, `date`, `last_mod_number`, `reason_for_modification`, `total_value`, `federal_value`, `awardee`, `funding_federal_agency`, and `contracting_federal_agency`.

6. If candidate lifecycle records remain after retrieval, judge relevance with dataset-specific evidence and record structure.
    - For `Search_Federal_Contract_Awards`, inspect both `descriptions` and `govtribe_ai_summary`.
    - For `Search_Federal_Contract_IDVs`, inspect both `description` and `govtribe_ai_summary`.
    - For `Search_Federal_Contract_Vehicles`, inspect both `descriptions` and `govtribe_ai_summary`.
    - If supporting transactions were retrieved, use those rows only for lifecycle evidence such as recent modifications, obligation activity, and modification reasons.
    - Use relationship fields such as `originating_federal_contract_opportunity`, `federal_contract_vehicle`, `federal_contract_idv`, `task_orders`, and `blanket_purchase_agreements` when they materially clarify likely follow-on structure.
    - Distinguish base awards, task orders, BPA calls, IDIQs, and master vehicles using documented dataset fields, not intuition.

7. Remove results that are not meaningfully relevant, are already closed out without meaningful follow-on potential, are not credibly likely recompetes, or are supported only by weak keyword overlap.
    - If the workflow began from a seed record, remove the seed itself from the discovery set before final ranking unless the user explicitly asked for a one-record evaluation.

8. If no relevant expiring work remains after review, say so clearly and stop.

9. If relevant expiring work remains after review, normalize the surviving results and extract key facts.
    - Use the explicit fields returned from awards, IDVs, vehicles, and supporting transactions.
    - When incumbent identity or parent-child context matters, use `Search_Vendors` with `vendor_ids` from award relationships and request `govtribe_id`, `govtribe_url`, `name`, `uei`, `dba`, `parent_or_child`, `parent`, `business_types`, `sba_certifications`, and `govtribe_ai_summary`.
    - Record and normalize:
        - Contract or vehicle name
        - Agency or buying office
        - Incumbent vendor
        - Vehicle or agreement type
        - Relevant lifecycle date such as `ultimate_completion_date`, `completion_date`, or `last_date_to_order`
        - Contract number or identifier
        - Short scope summary
        - Key follow-on or recompete signals

10. Rank the remaining results using the priority labels below, then perform a verification pass.
    - If the workflow began from a seed record, do not place the seed record in the final ranked recompete table unless the user explicitly asked to evaluate that exact record as the output item.
    - Remove weak, edge-case, or low-similarity matches and check whether the ranking still holds.
    - Rerun the cleaned cohort rather than trusting the first page.
    - Use `per_page` and additional pages as needed to confirm coverage.
    - If Step 3A was used, rerun at least one cleaned aggregation cohort on the same supporting tool you used for market sizing.
    - If the ranking shifts materially after cleanup, lower confidence and explain why.

### Priority Labels
Use these labels:
- **Very High**
- **High**
- **Medium**
- **Low**
- **Exclude**

Score results using these factors:
- Direct relevance to the target scope
- Credibility of the expiration or lifecycle date
- Evidence that the work is ongoing, recurring, or likely to be recompeted
- Agency or customer importance
- Similarity in scope, category, and vehicle type
- Presence of a clear incumbent
- Alignment between the result and the target in `descriptions` or `description`
- Alignment between the result and the target in `govtribe_ai_summary`
- Supporting transaction evidence, when recent modification activity materially sharpens the recompete signal

Guidance:
- **Very High**: Strong target fit, clear relevant lifecycle date, and strong signs the work is likely to continue or recompete
- **High**: Clear fit with good lifecycle evidence and a plausible follow-on path
- **Medium**: Potentially relevant, but one or more meaningful gaps remain
- **Low**: Only partial or adjacent fit; weakly supported
- **Exclude**: Clear mismatch in scope, agency, vehicle structure, timing, or textual evidence

Ranking rules:
    - If the workflow began from a seed record, do not include that seed in the final ranked table unless the user explicitly asked for a one-record evaluation of it.
    - Do not rank a result above **Medium** unless there is both strong scope relevance and a credible lifecycle signal such as `ultimate_completion_date`, `last_date_to_order`, or recent modification evidence that supports likely follow-on action.
    - Do not treat every expiring contract as a likely recompete.
    - Do not include a record in the final ranked table unless the evidence supports it as a likely recompete.

## Output Format
Use compact markdown tables by default for structured market-size summaries and ranked expiring-work results.

Use Mermaid only when denominator-versus-numerator comparisons or concentration patterns materially improve interpretation.
- Use `xychart-beta` for denominator-versus-numerator or simple window comparisons.
- Use `pie` only when one or a few players, vehicles, or set-aside buckets dominate the cohort.
- Only add a chart when it materially improves interpretation, include a short explanation, and fall back to the compact table if the data is sparse or Mermaid is unavailable.

Return the answer in this order:

1. **Search Scope Summary**
    - Briefly summarize how the target scope was interpreted.
    - If the workflow began from a seed record, identify it explicitly as the seed and summarize the key facts carried forward into the search.

2. **Search Approach**
    - Briefly explain which `Search_*` tools and lifecycle date fields were used.
    - Briefly state whether the Step 3A aggregation-only sizing branch was used or skipped and why.
    - Briefly explain how the aggregation-only sizing branch, keyword and filter-first row pass, and semantic pass were used.
    - Briefly note any date windows, filters, or aggregations applied.

3. **Market Size / Concentration Summary**
    - If Step 3A was used, start with a compact markdown table summarizing the major awardees, vehicles, set-aside patterns, classifications, or other dominant cohort signals.
    - If Step 3A was skipped because the scope was narrow, say so briefly and explain that direct row-level lifecycle review was more appropriate.
    - Briefly summarize the size of the scoped expiring market when Step 3A was used.
    - Briefly note whether the market looks concentrated or diffuse when aggregation evidence exists.
    - Only quantify denominator-versus-numerator framing when the same base filters remained intact through the likely-recompete screen.

4. **Top Likely Expiring Recompetes**
    - Present this section as a compact markdown table first.
    - Recommended columns: `Rank`, `Record`, `Agency`, `Incumbent`, `Lifecycle Date`, `Priority`.
    - Include only records that survived the likely-recompete screen.
    - When the workflow began from a seed record, the seed record itself is not eligible for this table unless the user explicitly asked for a one-record evaluation.
    - If rationale, caveats, or specific evidence do not fit cleanly in the table, add them immediately below the table as short notes.

5. **Why Others Were Excluded**
    - Briefly note weak matches, ambiguous records, or results with poor recompete signals.

6. **Overall Confidence**
    - State overall confidence in the output and why.
    - Call out ambiguities, unsupported date interpretations, or missing lifecycle details when they materially affect the answer.

## Citation Rules
- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.

## Grounding Rules
- Base claims only on provided context or GovTribe MCP tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or state that the goal cannot be fully completed from the available evidence.
- If a statement is an inference rather than a directly supported fact, label it as an inference.

# SBA Certification Graduation Dashboard

## User Input
- **Target scope:** [Agency / NAICS / PSC / vehicle / description of work]

## Goal
Use GovTribe MCP tools to build a **gap-ranked 8(a) exposure analysis** for **federal contract awards** and **federal contract IDVs** where both the vendor's **SBA 8(a) certification expiration date** and the record lifecycle date fall within the active analysis window. Default to the next 12 months unless the user clearly requests a shorter defensible window. Compute the date gap between lifecycle and certification and surface the strongest vendor and record-level exposures in a standard text answer.

## Required Input
The user must provide a **target scope** before analysis begins.

The target scope may include one or more of the following:
- Agencies or customers of interest
- NAICS, PSC, or other classifications
- Federal contract vehicles
- Set-aside type or eligibility posture
- A shorter lifecycle and certification date window
- A specific product, service, or work description if it is precise enough to narrow the results

Input rules:
- This workflow always searches both federal contract awards and federal contract IDVs.
- This workflow always uses `vendor_sba_8a_expiration_date_range` as the certification filter on award and IDV searches.
- Award and IDV rows do not return vendor certification date fields directly. Retrieve certification dates from `Search_Vendors` for the returned `awardee` vendor IDs, using `sba_cert_8a_expiration_date`.
- Default the certification and lifecycle windows to the next 12 months. Only narrow those windows when the user clearly requests a shorter defensible range that can be applied symmetrically to both datasets.
- Convert the target scope into the narrowest defensible shared scope bundle you can apply symmetrically to both datasets.
- If the user provides a product, service, prefer converting it into structured filters such as agency, NAICS, PSC, vehicle, set-aside, or a shorter date window when possible.
- Any scope derived from the target scope and applied to awards must also be applied to IDVs unless the user explicitly says otherwise.

## Workflow

### Steps
1. Call `Documentation` once with `collections=["govtribe-for-agents"]`, `article_names=["Choose a search mode and write queries", "Manage search context", "Date filtering", "Filter by related records and hierarchies", "Aggregations and leaderboards", "Troubleshoot search results"]`, and `max_tokens=12000` before any other GovTribe tool.
   - Treat the returned guide articles as binding for search behavior, query construction, date range shape, relationship filters, aggregation overview passes, search-context management, and troubleshooting used in this workflow.
   - Use the selected tool schema as the source of truth for tool-specific arguments, available fields, certification filters, lifecycle fields, sorts, aggregation keys, and response shapes.

### Important Dataset Field Differences
- Awards use `ultimate_completion_date_range` as the lifecycle filter and `ultimate_completion_date` as the returned lifecycle field.
- IDVs use `last_date_to_order_range` as the lifecycle filter and `last_date_to_order` as the returned lifecycle field.
- Awards use `set_aside_type` for set-aside output.
- IDVs use `set_aside` for set-aside output.
- Awards sort lifecycle retrieval with `completionDate`.
- IDVs sort lifecycle retrieval with `lastDateToOrder`.
- These names are not interchangeable across datasets. Do not assume awards and IDVs share the same field pattern.

2. Set the fixed SBA 8(a) certification configuration and shared scope bundle before searching.
   - Always use `vendor_sba_8a_expiration_date_range` on both `Search_Federal_Contract_Awards` and `Search_Federal_Contract_IDVs`.
   - Do not request `vendor_sba_cert_8a_expiration_date`; award and IDV rows do not return that field.
   - Retrieve exact certification dates by calling `Search_Vendors` for the returned awardee vendor IDs with `fields_to_return` including `govtribe_id`, `name`, `uei`, and `sba_cert_8a_expiration_date`.
   - Convert `target_scope` into a shared scope bundle. Apply the same scope, or the closest valid equivalent filters, to both `Search_Federal_Contract_Awards` and `Search_Federal_Contract_IDVs`.
   - If a requested scope cannot be applied defensibly to both datasets, say so explicitly and ask the user to clarify before searching.
   - Default the certification and lifecycle windows to `now/d` through `now+12M/d`.
   - If the user clearly requests a shorter defensible date window and it can be applied symmetrically to both datasets, use that narrower window instead.
   - Use lifecycle dates from award/IDV rows and certification dates from the joined vendor rows for exact row-level gap calculation, display, and interpretation.
3. Run a federal contract-award count and aggregation-overview pass with `Search_Federal_Contract_Awards`.
   - Use `ultimate_completion_date_range` for the lifecycle window established in Step 2.
   - Apply `vendor_sba_8a_expiration_date_range` for the certification window established in Step 2.
   - Apply the shared scope bundle from Step 2.
   - Use `per_page: 0` to measure the filtered award cohort and request aggregation highlights such as `top_awardees_by_dollars_obligated`, `top_contracting_federal_agencies_by_dollars_obligated`, `top_set_aside_types_by_dollars_obligated`, and, when useful, `top_federal_contract_vehicles_by_dollars_obligated`.
   - If the filtered award cohort is more than `250` rows, stop and ask the user to de-scope before continuing.
   - Suggested narrowing options: one or more specific agencies or customers, NAICS or PSC codes, a set-aside type, a shorter date window, or a precise product/service/work description.
4. Run the federal contract-award row retrieval workflow with `Search_Federal_Contract_Awards`.
   - Reuse the Step 3 lifecycle, certification, and shared scope filters.
   - Request `fields_to_return` explicitly. At minimum request `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `ultimate_completion_date`, `dollars_obligated`, `ceiling_value`, `set_aside_type`, `awardee`, `parent_of_awardee`, `contracting_federal_agency`, `naics_category`, `psc_category`, and `federal_contract_vehicle` only.
   - Sort retrieval by `ultimate_completion_date` ascending.
   - Retrieve `per_page: 50` rows at a time.
   - Review up to the first `100` scoped award rows sorted by lifecycle date. Do not attempt exhaustive pagination.
   - Only retrieve a second page when the first 50 rows are not enough to support a defensible ranking or pattern summary.
   - Exclude rows missing either `ultimate_completion_date` or `awardee.govtribe_id`.
   - Call `Search_Vendors` for the retained awardee vendor IDs and request `govtribe_id`, `name`, `uei`, and `sba_cert_8a_expiration_date`.
   - Exclude award rows whose joined awardee vendor row is missing `sba_cert_8a_expiration_date`.
   - Keep all remaining rows in the scoped cohort and compute `gap_days = ultimate_completion_date - certification_date`.
   - Interpret `gap_days` as: positive means the work extends past certification expiration; zero or negative means the work ends on or before certification expiration.
5. Run a federal contract IDV count and aggregation-overview pass with `Search_Federal_Contract_IDVs`.
   - Use `last_date_to_order_range` for the lifecycle window established in Step 2.
   - Apply `vendor_sba_8a_expiration_date_range` for the certification window established in Step 2.
   - Apply the shared scope bundle from Step 2.
   - Use `per_page: 0` to measure the filtered IDV cohort and request aggregation highlights such as `top_awardees_by_doc_count`, `top_contracting_federal_agencies_by_doc_count`, `top_set_aside_types_by_doc_count`, and `top_vehicles_by_doc_count`.
   - If the filtered IDV cohort is more than `100` rows, stop and ask the user to de-scope before continuing.
   - Suggested narrowing options: one or more specific agencies or customers, NAICS or PSC codes, a set-aside type, a shorter date window, or a precise product/service/work description.
   - If the top vehicle buckets are dominated by names containing `Multiple Award Schedule`, `MAS`, `FSS`, `GWAC`, or `OASIS`, and those buckets account for more than 60% of the scoped IDV cohort, tell the user the pool is MAS/GWAC-heavy, suggest narrowing before row retrieval, and offer to exclude `Federal Supply Schedule` from `federal_contract_idv_types` if the user wants to narrow.
6. Run the federal contract IDV row retrieval workflow with `Search_Federal_Contract_IDVs`.
   - Reuse the Step 5 lifecycle, certification, and shared scope filters.
   - Request `fields_to_return` explicitly. At minimum request `govtribe_id`, `govtribe_url`, `name`, `contract_number`, `last_date_to_order`, `ceiling_value`, `set_aside`, `awardee`, `parent_of_awardee`, `contracting_federal_agency`, `naics_category`, `psc_category`, and `federal_contract_vehicle` only.
   - Sort retrieval by `last_date_to_order` ascending.
   - Retrieve `per_page: 50` rows at a time.
   - Review up to the first `100` scoped IDV rows sorted by lifecycle date. Do not attempt exhaustive pagination.
   - Only retrieve a second page when the first 50 rows are not enough to support a defensible ranking or pattern summary.
   - Exclude rows missing either `last_date_to_order` or `awardee.govtribe_id`.
   - Call `Search_Vendors` for the retained awardee vendor IDs and request `govtribe_id`, `name`, `uei`, and `sba_cert_8a_expiration_date`.
   - Exclude IDV rows whose joined awardee vendor row is missing `sba_cert_8a_expiration_date`.
   - Keep all remaining rows in the scoped cohort and compute `gap_days = last_date_to_order - certification_date`.
   - Interpret `gap_days` as: positive means the work extends past certification expiration; zero or negative means the work ends on or before certification expiration.
7. Synthesize the final analysis from the retained award and IDV rows only.
   - Keep awards and IDVs separate throughout the answer.
   - Base all counts, pattern claims, summaries, and top-exposure tables only on the scoped rows that survived the active date-window filters and have both required dates after the vendor lookup.
   - Do not merge awards and IDVs into a single ranked table.
   - Rank vendors and representative rows by `gap_days` descending, then value descending.
   - Add a row-level `Set-Aside Alignment` label using returned set-aside text only:
     - `matching expected set-aside`
     - `other set-aside`
     - `no set-aside used`
   - Treat `8(a) Sole Source` and `Competitive 8(a)` as `matching expected set-aside` for this fixed 8(a) workflow.
   - For IDVs, if `federal_contract_vehicle` contains `Multiple Award Schedule`, `MAS`, `FSS`, `GWAC`, or `OASIS`, flag the record as a shared vehicle ceiling and exclude that ceiling from aggregate exposure totals.
   - Keep pattern commentary qualitative and limited to what the scoped rows and aggregation-overview passes clearly support.
   - Focus on the strongest vendor and record-level exposures. Do not attempt an exhaustive full-cohort dashboard.
8. Perform a verification pass before finalizing the dashboard.
   - Recheck any row with missing vendor identity context, conflicting dates, or a filter/display mismatch.
   - Explicitly compare `awardee` and `parent_of_awardee`.
   - If both are present and differ, note the parent relationship in the answer and do not silently merge vendors solely because they share a parent.
   - Flag rows where vendor identity appears ambiguous or fragmented across LLC/subsidiary variants.
   - If one dataset returns no defensible rows, say so clearly instead of padding the dashboard.
   - Lower confidence if the remaining results are sparse, MAS/GWAC-heavy, concentrated in one narrow pocket, or dependent on ambiguous parent/child consolidation.

# Output Format

Return the answer in this order:

1. **8(a) Certification Filter and Shared Scope**
   - Briefly summarize the fixed 8(a) certification focus, the lifecycle and certification windows, and any shared scope the user applied across both datasets.
2. **Search Approach**
   - Briefly explain which searches were run, how the shared scope was applied symmetrically, how the count and aggregation passes were used, and how `gap_days` was computed from returned rows.
3. **Cohort Overview**
   - Start with one compact markdown table.
   - Recommended columns: `Dataset`, `Scoped Count`, `Rows Reviewed`, `Earliest Lifecycle Date`, `Latest Lifecycle Date`, `Top Signals`.
4. **Top Award Exposures**
   - Present this section as a compact markdown table first.
   - Recommended columns: `Vendor`, `Award`, `Agency`, `Lifecycle Date`, `Certification Date`, `Gap Days`, `Set-Aside Alignment`, `Exposure`.
   - Focus on the strongest and most decision-useful rows rather than exhausting the full cohort.
5. **Top IDV Exposures**
   - Present this section as a compact markdown table first.
   - Recommended columns: `Vendor`, `IDV`, `Agency`, `Last Date to Order`, `Certification Date`, `Gap Days`, `Set-Aside Alignment`, `Ceiling / Exposure`.
   - Flag shared vehicle ceilings clearly in the table or a short note below it.
6. **Key Patterns**
   - Briefly summarize agency concentration, set-aside alignment, shared vehicle ceiling posture, and the vendors with the largest positive `gap_days`.
7. **Risks, Gaps, or Unknowns**
   - Briefly note missing dates, parent-child ambiguity, shared ceiling limitations, MAS/GWAC-heavy IDV pools, or any de-scope limits that affected the answer.
8. **Overall Confidence**
   - State overall confidence and explain why.

Do not create a React dashboard, code artifact, serialized JSON payload, or second output format. Return a normal text answer with compact markdown tables only.

## Citation Rules

- Only cite sources retrieved in the current workflow.
- Never fabricate citations, URLs, IDs, or quote spans.
- Use exactly the citation format required by the host application.
- Attach citations to the specific claims they support, not only at the end.

## Grounding Rules

- Base claims only on provided context or GovTribe MCP tool outputs.
- If sources conflict, state the conflict explicitly and attribute each side.
- If the context is insufficient or irrelevant, narrow the answer or state that the goal cannot be fully completed from the available evidence.
- If a statement is an inference rather than a directly supported fact, label it as an inference.