Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bonfire_search_opportunities

Read-only

Retrieve all currently-open solicitations from a Bonfire government org, showing reference number, name, close date, and link.

Instructions

List a government's currently-OPEN solicitations on Bonfire (keyless; {org}.bonfirehub.com/opportunities/rss, RSS 2.0). Input org (the subdomain slug from bonfire_list_organizations, e.g. 'harriscountytx', 'broward', 'u-46'; REQUIRED), limit(1..200)/offset. Returns { org, opportunities:[{ referenceNumber, name, description, closeDate, link, pubDate }] } + honest _meta. HONESTY: the RSS is the COMPLETE set of the org's currently-open opportunities (no server pagination), so totalAvailable = the exact open-opportunity count (never a page length) and this tool pages over it client-side; an empty feed (returned 0) means no open opportunities right now (honest empty, complete:true); closeDate is parsed best-effort from the description; a 429/5xx/404/timeout THROWS (never a fake empty); a 200 non-RSS body ⇒ schema_drift; a bad org ⇒ invalid_input pre-fetch. Fixed-suffix SSRF (.bonfirehub.com) + redirect:error. Keyless (Bonfire's auth-gated directory API is NOT used). STATE-LEVEL bid feeds on open-data portals are NOT in this directory: TX TxDOT lettings, advertised and taking bids = socrata_query data.texas.gov qh8x-rm8r; IL CDB capital bids that are ANTICIPATED and NOT YET POSTED = socrata_query data.illinois.gov 6rb8-ntpm (~48 rows, not IL's full register). Map: resource samgov://data-map/state-local.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
orgYesThe Bonfire org subdomain slug (from bonfire_list_organizations `org`), e.g. 'harriscountytx', 'broward', 'u-46'. REQUIRED. Lowercase alnum/hyphen; a bad slug ⇒ invalid_input pre-fetch.
limitNoOpportunities per page, 1..200, default 50. The RSS is the complete open set; this pages over it.
offsetNo0-based offset; page with _meta.pagination.nextOffset. totalAvailable = the exact open-opportunity count.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.12.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only indicate readOnlyHint and openWorldHint, but the description goes far beyond: explains the RSS is the complete set (no server pagination), honest empty behavior, error handling (throws on failures, schema_drift on non-RSS), SSRF protections, and keyless nature. This is comprehensive and fully aligns with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence serves a purpose; it front-loads the primary function and then details behavior. It is longer than ideal but packed with actionable detail without redundancy, and the structure logically progresses from core use to edge cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description fully specifies the return structure ({ org, opportunities, _meta }) and explains all necessary behaviors: error handling, pagination semantics, and data completeness. Given the moderate complexity and the absence of output schema, this is complete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for all three parameters (org, limit, offset) with 100% coverage, but the description adds critical semantics: how 'org' is derived from bonfire_list_organizations, the exact range for limit, and the meaning of totalAvailable as the exact open-opportunity count. This enhances the schema meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists a government's currently-open solicitations on Bonfire, specifying the exact RSS source and keyless access. It distinguishes itself from siblings like opengov_search_solicitations and bonfire_list_organizations by focusing on open solicitations and providing the subdomain slug source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides when to use this tool (for open Bonfire solicitations) and what not to use it for (state-level bid feeds like TX TxDOT and IL CDB, which should use socrata_query), naming exact datasets and sources. This is a model of routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools