Aperture Contracts

Report how current the underlying datasets are. Returns (response_format='json'): { "contracts": {"total": int|null, "latest_posted_date": str|null, "open_now": int|null, "*_is_exact": bool}, "last_sync": {"source": str, "status": str, "started_at": str, "completed_at": str|null}|null } Use this to tell the user how stale results may be before relying on them.

aperture_data_status

Fetch the complete record for a single opportunity, including description. Returns (response_format='json') the full row as an object: `description`, `description_link`, `point_of_contact`, `attachments`, NAICS, set-aside, posted date and response deadline. The bulky `raw_json` column is stripped to protect context. Raises a clear error naming the identifier if no matching row exists.

aperture_get_opportunity

Rank open federal opportunities by how well this company fits them and whether it is eligible to bid at all. Scores every open solicitation against the profile and returns the best matches first, each carrying `fit_score` (0-100), `fit_tier`, and `fit_reasons` — the factors that produced the score. The score is a heuristic FIT estimate, not a statistical probability drawn from award history: it ranks opportunities against each other for this company, driven mainly by set-aside eligibility and NAICS fit. Solicitations the company is legally ineligible for — a set-aside it does not hold — score 0 and are dropped unless `include_ineligible` is set. For a deep read of any single result, follow up with aperture_get_opportunity and aperture_read_document — the full solicitation carries mandatory requirements this scorer cannot see. With no `profile` argument this uses the stored one. If nothing is stored, it says so rather than scoring against an empty profile — an empty profile ranks nothing meaningfully, and a confident-looking list built from no information is worse than a request for four facts.

aperture_match_company

Return the extracted text of an attached opportunity document (e.g. a NOFO or solicitation), so an LLM can answer from the source rather than the summary. Documents can be tens of thousands of characters; use `offset`/`length` to page through a long one. Returns: { "file_description": str, "char_count": int, "offset": int, "returned": int, "has_more": bool, "text": str, "url": str }

aperture_read_document

Return the caller's stored company profile, or `{"found": false}` if none exists. When nothing is stored, ask for the fields that actually move a score — NAICS codes, socioeconomic certifications, target agencies and award range — rather than a generic description. Certifications matter most: a set-aside the company does not hold is unwinnable, and one it does hold is where its real advantage lives.

aperture_get_company_profile

Store a company profile so it does not have to be re-gathered every conversation. Upserts on (user, company name): saving twice updates rather than duplicating, and a different name creates a separate company — which is what someone managing several entities needs. Ask before calling this. A profile is remembered across conversations, and the person should know that is happening rather than discover it later.

aperture_save_company_profile

Search SAM.gov federal contract solicitations. Returns (response_format='json') an object shaped: { "results": [ { "id": str, "notice_id": str, "sol_number": str|null, "title": str, "department": str|null, "sub_tier": str|null, "office": str|null, "naics_code": str|null, "set_aside_type": str|null, "ptype": str|null, "posted_date": str|null, "response_deadline": str|null, "archive_date": str|null, "award_amount": int|null, "pop_city": str|null, "pop_state": str|null, "pop_zip": str|null } ], "pagination": { "count": int, "total_count": int|null, "limit": int, "offset": int, "has_more": bool, "next_offset": int|null } } With response_format='markdown' the same data is rendered as readable text. `pop_city` / `pop_state` / `pop_zip` are the PLACE OF PERFORMANCE — where the work is done. They are null for roughly 43% of open solicitations because SAM does not always state them. Null means unstated, NOT local: the contracting office address is a different field and is not where the work happens. Never describe a result set as being in a state unless each row you are describing actually carries that state. Filtering by `place_of_performance_state` therefore HIDES every notice that left the field blank, work in that state included. When you use it the response carries `place_of_performance_coverage`, counting exactly how many matching notices were excluded for having no stated location. Report that count and say the list is not exhaustive. Presenting a filtered list as "the opportunities in <state>" is wrong by roughly the size of that number. Note: `query` matches the TITLE only. Full solicitation text is not indexed for search; retrieve it for a specific notice via aperture_get_opportunity. Results are DEDUPLICATED by solicitation number. SAM issues a new notice for every amendment, so one solicitation can appear a dozen times; each result here is one solicitation, showing its most recent version, with `amendment_count` recording how many notices were collapsed (a high count means the requirement is still changing). Because of that, `pagination.total_count` counts raw notices, INCLUDING every repost, and is an upper bound rather than a count of opportunities. When `total_count_includes_amendment_reposts` is set it is not the answer to "how many opportunities are there" and must not be given as one, even qualified afterwards. Asked for a number, answer with the distinct solicitations actually retrieved and page until you have them all if the user wants a total; `total_count` may only appear as an explicit ceiling ("at most N notices, which collapse to the M solicitations below"). Reporting the raw total as the headline figure overstates the real pipeline by a third. If the user is describing a COMPANY and asking what it should go after, prefer aperture_match_company instead: it applies eligibility gates and returns a scored, ranked shortlist rather than an unranked list.

aperture_search_contracts

Find opportunities by semantic similarity to a natural-language query. Unlike aperture_search_contracts (which matches literal words in the title/description), this embeds the query and ranks opportunities by meaning, so 'rural broadband' also finds 'Broadband Infrastructure Program'. Prefer it for conceptual or paraphrased searches; use the keyword tools for exact codes (NAICS, CFDA), agencies, or filters. Returns the shared envelope: { "results": [...], "pagination": {...} }, with contract solicitations ranked by `similarity` (0-1, 1 = closest). Each row carries `source` ("contract") plus that dataset's fields. Retrieve full detail with aperture_get_opportunity. If the user is asking what a SPECIFIC COMPANY should pursue, prefer aperture_match_company — it scores eligibility and fit rather than similarity.

aperture_semantic_search