# G2X browser tool reference

This guide describes how to discover and use G2X's page-scoped browser tools. Tools and allowed actions depend on the active G2X page and the current account. A name in a reference catalog does not mean the tool is available to your browser. For a signed-in account, a tool returns the same fields and results the G2X page shows that account, on every plan.

## Entry points

1. Open a relevant G2X page in a browser that supports the site's WebMCP tools. Use the user's existing session when authorized.
2. Discover the active tools through your browser's supported interface. Call `g2x_describe_surface` first if it is present. Recheck after moving to a different page.
3. Read the selected tool's input schema before calling it. Use the returned record URLs, identifiers, and next steps.
4. If a tool is absent or access is denied, use the accessible product or `g2x_get_access_options` when available. Do not install a substitute browser API or call hidden transports to force access.

The [WebMCP preflight index](https://g2x.com/.well-known/webmcp-tools.json) lists tool definitions and candidate surfaces. The active browser catalog is authoritative for the current page. The index is metadata, not an executable connection.

The [read-transport OpenAPI schema](https://g2x.com/openapi.json) and [API catalog](https://g2x.com/.well-known/api-catalog) describe discovery and the HTTP transport behind enabled browser reads. They do not establish a remote MCP endpoint, issue credentials, or authorize background collection. They may be unavailable when browser reads are not offered.

## Choose the right tool family

| User's task | Candidate tools | What to check |
| --- | --- | --- |
| Understand the page or access | `g2x_describe_surface`, `g2x_get_page_context`, `g2x_get_access_options` | Page context contains metadata, not page content or records. |
| Find curated intelligence | `g2x_search_intel` | Article previews only; use the returned article links. Start on a surface that actually exposes the search, such as the homepage. |
| Resolve a company name | `g2x_search_companies` | Preserve multiple legal-entity matches; use returned identities. The homepage can expose this search. |
| Find opportunities | `g2x_search_opportunities`, `g2x_search_small_business_programs`, `g2x_search_grants` | Match the collection and schema. SLED, DIBBS, and SBIR/STTR use the program-specific tool. |
| Research awards | `g2x_search_awards`, `g2x_search_contracts`, `g2x_search_vehicles` | Keep record families, agency roles, and financial measures distinct. |
| Inspect a record | `g2x_get_record`, `g2x_compare_records`, `g2x_profile_incumbent`, `g2x_search_protests` | Use supported record types and resolved IDs; some tools require additional access. |
| Find SAM documents | `g2x_get_record_documents` | SAM opportunities only. A listing does not supply the full text. Use returned viewer/download links when available. |
| Investigate relationships | `g2x_get_graph_neighborhood` | Availability and account access must be established; absence of a result is not evidence that no relationship exists. |
| Organize selected work | `g2x_watch_records`, `g2x_unwatch_records`, `g2x_add_to_pipeline`, `g2x_move_pipeline_item`, `g2x_annotate_record`, `g2x_tag_records`, `g2x_undo` | Follow the user's requested change, ownership, allowed stages, and returned undo information. No pipeline-creation tool is promised. |
| Reuse a search | `g2x_save_search`, `g2x_set_alert` | Saving does not run a search in the background; alert delivery requires in-page confirmation. |
| Save a deliverable | `g2x_create_artifact`, `g2x_export_records`, `g2x_share_artifact` | These can create saved output or prepare sharing. Respect the user's scope and follow confirmation. Verify the returned G2X artifact. |
| Ask Lumen | `g2x_ask_lumen`, `g2x_get_lumen_task` | Starting research creates a task; completion must be checked separately. |

The earlier `g2x_get_more_data_options` name can appear as an alias for access guidance. Prefer the name actually supplied by the browser.

## Read results accurately

A successful tool response contains `data` and may include G2X `citations`, access information, and a `next_step`. Use the operation's result status as well as the transport outcome. Inspect whether the result is complete, partial, empty, or unavailable before drawing a conclusion. A signed-in account sees the fields its G2X page shows; when `entitlement` names withheld fields or records, they are unknown, not zero. A bounded page of results is not a full market total.

Use `record_url` links as returned. Document tools can return a parent record link plus a separate viewer or download link. Keep the record as the user's research destination and cite an accessed document where it supports a claim.

Use pagination only to finish the user's bounded request. Follow the supplied cursor and stop when there is no continuation or access requires a different next step. Do not loop for bulk collection. An unsuccessful read is not proof of no results; a response that could not be completed should not be presented as a complete market assessment.

For writes, report the actual result and retain its operation/undo information privately for the authorized follow-up. Check the current state before repeating an uncertain write. A returned confirmation requirement is not permission to bypass the user.

## Limits and versions

Browser tool calls are counted for the signed-in account, or for the visitor when signed out. The same limits apply on every page:

| Limit | Allowance |
| --- | --- |
| Calls to one tool in a session | 30 per minute |
| Calls in a session | 100 per hour |
| Calls for an account | 500 per day |

Checking a started Lumen task with `g2x_get_lumen_task` uses a separate allowance of 30 checks per minute for the account. These limits apply to browser tools.

When a limit is reached, the tool returns `rate_limited` with `retry_after_seconds`, and the HTTP transport sends the same wait as `Retry-After`. Wait at least that long before retrying the same bounded request. Do not rotate sessions, accounts, or networks to continue.

Product allowances are shared with the G2X pages. A Free account's daily allowances for contract, vehicle, and IDV details, forecast details, and company profiles count a record opened through `g2x_get_record`, `g2x_compare_records`, or `g2x_profile_incumbent` exactly as opening its page, and a record already opened that day costs nothing. When an allowance is used, the tool returns `not_entitled` with a `next_step` and `retry_after_seconds` until the allowance resets; `g2x_compare_records` returns the records still within the allowance and reports the rest in `entitlement.withheld_count` with `reason` `meter_limit`. Follow the `next_step` or wait; do not retry through another channel.

Read-transport requests send `schema_version` `2026-09-01`. Any other value fails with `invalid_argument` and names the accepted version. The [read-transport OpenAPI schema](https://g2x.com/openapi.json) publishes the current version as `info.version`. A breaking change to request or response shapes uses a new `schema_version`, published there and in this reference.

## Small examples

These are example input objects for tools already discovered in the active browser. They do not establish a connection or promise that every account can execute them. Read the current schema before use. Replace example IDs with identifiers returned by G2X.

Find federal health editorial previews on an eligible discovery surface:

```json
{"tool":"g2x_search_intel","input":{"query":"HHS cybersecurity","vertical":"health","limit":5}}
```

Find a bounded set of federal opportunities on the SAM opportunity search surface:

```json
{"tool":"g2x_search_opportunities","input":{"query":"cybersecurity","funding_agency":"Department of Health and Human Services","limit":5}}
```

Find DIBBS opportunities on its search surface:

```json
{"tool":"g2x_search_small_business_programs","input":{"program":"dibbs","query":"valve","limit":5}}
```

Resolve a company name on an eligible discovery surface:

```json
{"tool":"g2x_search_companies","input":{"query":"Example Federal Services","limit":5}}
```

Ask what to do when an integration needs a larger or automated data workflow:

```json
{"tool":"g2x_get_access_options","input":{"need":"bulk_or_automation"}}
```

For a multi-step task, search first, open a returned G2X record, rediscover the tools on that page, and use its resolved ID with a supported detail tool. Do not invent an ID or infer that an input accepted by one tool is accepted by another.

## API and remote MCP connections

The browser integration, G2X API access, and a remote MCP connection are separate entry points. [Developer access](https://g2x.com/developer) is the public place to confirm the available connection for the user's environment. An existing connected agent should use its actual supplied tool catalog and granted scope.

For eligible G2X API users, API key management is in **Settings → Account → API Keys**. Follow the account's API documentation for supported posts, events, and eligible reads of the user's GSA eBuy RFQs in G2X. The presence of an API key does not grant every procurement dataset or establish a remote MCP connection. Do not create or revoke keys unless the user has requested it; keep credentials in the user's secret manager.

G2X's internal event-tool names or another agent's installed connector are not connection instructions. Do not advertise a CLI or a universal self-serve MCP setup based on this guide.