What makes a tool agent-ready: 5 checks from building a SAM.gov tool for agents
We built a SAM.gov contract-opportunities tool because agents kept bouncing off a website made for people. SAM.gov is the official U.S. source for federal contract notices. An agent that wants active solicitations shouldn’t have to click through search results, or depend on a shared API key pasted into a chat.
The tool is live on the Apify Store as samgov-tools/samgov-opportunities. What follows is what we learned while building it, written as five checks we now use when we call a tool agent-ready. These are working notes from one build, not a standard, and not a claim that every listing in our directory already passes all five.
1. Can an agent call it and get a record back?
Most of the useful web is still a page. Agents need a record: one object per thing, with field names that stay put.
Our Actor returns one normalized item per SAM.gov notice, in JSON, CSV, or Excel. Stable fields include noticeId, title, solicitationNumber, type, postedDate, responseDeadline, naicsCode, setAside, agency path, place of performance, points of contact, and the official SAM.gov link (uiLink). Missing values are null, not an empty string or a key that appears in some rows and vanishes in others.
If a tool only gives you HTML, or a slightly different JSON blob every time, the agent spends its budget parsing instead of working.
2. Is the data from an official source, and do you say how fresh it is?
We don’t scrape SAM.gov pages. The default path streams the official public daily extract of active contract opportunities, ContractOpportunitiesFullCSV, published by SAM.gov Data Services. That file is up to about a day old. Each item carries dataSource (sam.gov-daily-extract or sam.gov-api) and, in extract mode, extractDate from the file’s Last-Modified header.
If you need live data, pass your own free public API key from a SAM.gov account. The Actor then uses the official Get Opportunities Public API, documented by GSA. Your key is a secret input, used only during the run, and is never written into the dataset. We also strip any api_key query parameter from stored links.
The tradeoff is written down. The extract needs no key and covers active notices. The API can include inactive notices in a one-year window, but a new personal key can be tightly rate-limited, and in API mode description is a URL, not the notice text.
3. Can the agent actually authenticate?
A public API that still needs a human to click through a portal is not ready for an agent.
The default extract path needs no SAM.gov key at all. That’s why we made it the default. The live path uses a key the operator already has, or can create on the SAM.gov Account Details page. We don’t use a shared key, and we don’t ask the agent to sign in to sam.gov in a browser.
You still need an Apify token to run the Actor, or to reach it through Apify’s MCP server. That’s a platform credential, not a SAM.gov login.
4. Is the price visible before the call, and billed per useful result?
Agents will retry, loop, and over-fetch if you let them. A monthly plan with a soft cap is a trap. Pay-per-use only helps if the unit is something the caller can cap.
This Actor is $2 per 1,000 opportunities stored, or $0.002 each, on Apify’s pay-per-event model. Platform usage for the run is included. You are charged only for opportunities that are successfully stored. Notices that get filtered out, duplicates within a run, rejected records, and download or API errors don’t generate a charge. maxItems defaults to 10 and tops out at 10,000, and the budget is checked before every charged item.
A few limits we should say out loud: runs are independent, so the same query can charge for the same notice again, and if a run fails after some items are stored, those items may already have been billed. There is no cross-run deduplication.
5. Are the filters structured, and are the gaps written down?
An agent needs inputs it can fill in, not a search box with hidden rules.
You can filter by title keywords, NAICS (a prefix match on the extract, the official ncode on the API), set-aside code, notice type (the official ptype values, such as solicitation or sources sought), place-of-performance state, and a posted-date range of at most one calendar year. Empty input returns up to 10 recent active notices. Filters can also return nothing. That’s a valid result, not an error.
We also document the gaps, because an agent will hit them. The extract has no attachment list, so resourceLinks is null in that mode. The Actor does not download attachments, which can have their own access rules. Keyword search is a title search, not full-text. Date formats differ between the extract and the API. The official API even misspells reponseDeadLine. We accept both spellings and expose a single responseDeadline.
That last one is small. It’s also the kind of thing that quietly breaks a workflow if you pretend the upstream API is tidy.
What we’re doing with this
These five checks are how we now look at tools, including our own. AgentReady Tools is a curated directory of tools we think are closer to this bar: clean callable data, pay-per-use pricing, and some control over what an agent can do and spend. As of 15 November 2026 the catalog at /tools.json lists 74 tools, including this SAM.gov Actor and a few others we built (URL screenshot, ATS jobs). The site also publishes /llms.txt and a public, unauthenticated MCP server at https://agentready-tools.com/mcp, with three read-only tools: search_tools, get_tool, and list_categories.
Spend Controls is a demand test, not a live product. Some directory links are affiliate links.
If you’re building for agents, I’d start with check 1 and check 5. Structured output and honest gaps save more time than a prettier landing page.
- The tool: apify.com/samgov-tools/samgov-opportunities
- Official Get Opportunities API: open.gsa.gov/api/get-opportunities-public-api