Skip to main content
Glama

Sam Entity Search

sam_entity_search
Read-onlyIdempotent

Look up federal contractors registered in SAM.gov by business name, UEI, or CAGE code. Returns UEI, CAGE, legal and DBA name, address, NAICS and PSC codes, entity structure, registration and expiration dates, small-business/SBA certifications, and whether the entity carries an exclusion flag. Answers keyless from a local mirror of SAM.gov's public Entity Registration extract, ranking an exact UEI/CAGE/legal-name match above any fuzzy name hit and active registrations above expired ones. Every response carries a mirror field with the snapshot date and its age in days, the public entity extract is published MONTHLY, so an answer can legitimately be several weeks old; pass live:true with an API key when you need the registry as of today.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "limit": 2,
      "business_name": "Lockheed Martin Corporation"
    },
    "name": "sam_entity_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
liveNoForce a live SAM.gov API lookup instead of the mirror. Needs _apiKey. Use only when you specifically need registrations changed since the mirror snapshot, the live entity API is capped at 10 requests/day on the shared platform key.
limitNoNumber of results (1-100, default 10).
naicsNoFilter by NAICS code (optional), matches the primary NAICS or any NAICS the entity lists. Not sure of the code? naics_search turns industry words into NAICS codes; naics_lookup explains one.
stateNoFilter by 2-letter US state code (e.g., "VA", "CA")
offsetNoRows to skip for paging (default 0).
_apiKeyNoOptional, omit it. This search answers keyless from the local snapshot of SAM.gov's public Entity Registration extract; a key is needed only for live:true.
active_onlyNoOnly entities with an active registration (default false, expired registrations are returned but sorted below active ones).
business_nameYesWhat to search for: a legal/DBA business name, or an exact UEI or CAGE code. Accepts query / q / name as aliases.
small_businessNoFilter to only small business entities (optional)

Output Schema

NameRequiredDescriptionDefault
entitiesYes
total_recordsYesTotal number of matching entities in SAM

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / naics / description
      Previous value: -"Filter by NAICS code (optional), matches the primary NAICS or any NAICS the entity lists."New value: +"Filter by NAICS code (optional), matches the primary NAICS or any NAICS the entity lists. Not sure of the code? naics_search turns industry words into NAICS codes; naics_lookup explains one."
  2. Changed4 schema fields changed
    • changedInput schema / properties / _apiKey / description
      Previous value: -"Optional — omit it. This search answers keyless from the local snapshot of SAM.gov's public Entity Registration extract; a key is needed only for live:true."New value: +"Optional, omit it. This search answers keyless from the local snapshot of SAM.gov's public Entity Registration extract; a key is needed only for live:true."
    • changedInput schema / properties / active_only / description
      Previous value: -"Only entities with an active registration (default false — expired registrations are returned but sorted below active ones)."New value: +"Only entities with an active registration (default false, expired registrations are returned but sorted below active ones)."
    • changedInput schema / properties / live / description
      Previous value: -"Force a live SAM.gov API lookup instead of the mirror. Needs _apiKey. Use only when you specifically need registrations changed since the mirror snapshot — the live entity API is capped at 10 requests/day on the shared platform key."New value: +"Force a live SAM.gov API lookup instead of the mirror. Needs _apiKey. Use only when you specifically need registrations changed since the mirror snapshot, the live entity API is capped at 10 requests/day on the shared platform key."
    • changedInput schema / properties / naics / description
      Previous value: -"Filter by NAICS code (optional) — matches the primary NAICS or any NAICS the entity lists."New value: +"Filter by NAICS code (optional), matches the primary NAICS or any NAICS the entity lists."
  3. Changed1 schema field changed
    • changedOutput schema / properties / entities / items / properties / business_types / type
      Previous value: -"array"New value: +[
      +  "array",
      +  "string"
      +]
  4. Changed1 schema field changed
    • changedOutput schema / properties / entities / items / properties / sba_certifications / type
      Previous value: -"array"New value: +[
      +  "array",
      +  "null"
      +]
  5. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "_apiKey": "your-samgov-api-key",
      -    "business_name": "Acme Tech Solutions",
      -    "state": "VA"
      -  },
      -  {
      -    "_apiKey": "your-samgov-api-key",
      -    "business_name": "GreenTech Inc",
      -    "naics": "541511",
      -    "small_business": true
      -  }
      -]New value: +[
      +  {
      +    "business_name": "Lockheed Martin Corporation",
      +    "limit": 2
      +  },
      +  {
      +    "business_name": "CH5WNENNFHX5"
      +  },
      +  {
      +    "business_name": "GreenTech",
      +    "naics": "541511",
      +    "small_business": true,
      +    "state": "VA"
      +  }
      +]
  6. Changed8 schema fields changed
    • changedInput schema / properties / _apiKey / description
      Previous value: -"SAM.gov API key — required. Free at https://sam.gov/content/entity-information; a key on an account with a SAM.gov role allows 1,000 requests/day."New value: +"Optional — omit it. This search answers keyless from the local snapshot of SAM.gov's public Entity Registration extract; a key is needed only for live:true."
    • addedInput schema / properties / active_only
      Added value: +{
      +  "description": "Only entities with an active registration (default false — expired registrations are returned but sorted below active ones).",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / business_name / description
      Previous value: -"Legal business name to search for"New value: +"What to search for: a legal/DBA business name, or an exact UEI or CAGE code. Accepts query / q / name as aliases."
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Number of results (1-100, default 10).",
      +  "type": "number"
      +}
    • addedInput schema / properties / live
      Added value: +{
      +  "description": "Force a live SAM.gov API lookup instead of the mirror. Needs _apiKey. Use only when you specifically need registrations changed since the mirror snapshot — the live entity API is capped at 10 requests/day on the shared platform key.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / naics / description
      Previous value: -"Filter by primary NAICS code (optional)"New value: +"Filter by NAICS code (optional) — matches the primary NAICS or any NAICS the entity lists."
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Rows to skip for paging (default 0).",
      +  "type": "number"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "business_name",
      -  "_apiKey"
      -]New value: +[
      +  "business_name"
      +]
  7. Changed1 schema field changed
    • changedInput schema / properties / _apiKey / description
      Previous value: -"SAM.gov API key"New value: +"SAM.gov API key — required. Free at https://sam.gov/content/entity-information; a key on an account with a SAM.gov role allows 1,000 requests/day."
  8. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "entities": {
      +      "items": {
      +        "properties": {
      +          "address": {
      +            "description": "Physical business address",
      +            "properties": {
      +              "city": {
      +                "description": "City",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "country": {
      +                "description": "Country code",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "line1": {
      +                "description": "Address line 1",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "state": {
      +                "description": "State or province code",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "zip": {
      +                "description": "Zip/postal code",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "business_types": {
      +            "description": "List of business type classifications",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "cage_code": {
      +            "description": "CAGE Code identifier",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "dba_name": {
      +            "description": "Doing Business As name",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "entity_url": {
      +            "description": "Entity website URL",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "expiration_date": {
      +            "description": "SAM registration expiration date",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "legal_business_name": {
      +            "description": "Legal business name",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "primary_naics": {
      +            "description": "Primary NAICS code",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "registration_date": {
      +            "description": "Date of initial SAM registration",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "registration_status": {
      +            "description": "SAM registration status",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "sba_certifications": {
      +            "description": "SBA business type certifications held",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "uei": {
      +            "description": "Unique Entity Identifier",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "total_records": {
      +      "description": "Total number of matching entities in SAM",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "total_records",
      +    "entities"
      +  ],
      +  "type": "object"
      +}
  9. Changed1 schema field changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "_apiKey": "your-samgov-api-key",
      +    "business_name": "Acme Tech Solutions",
      +    "state": "VA"
      +  },
      +  {
      +    "_apiKey": "your-samgov-api-key",
      +    "business_name": "GreenTech Inc",
      +    "naics": "541511",
      +    "small_business": true
      +  }
      +]
  10. First observed

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered structurally. Beyond that, the description adds genuinely useful behavior: results come from a local mirror, every response carries a `mirror` field with snapshot age, the extract refreshes monthly so answers may be weeks stale, and live:true requires an API key. A 4 is warranted because staleness and the key requirement are not derivable from annotations, though the description does not describe pagination/limit behavior beyond the schema.

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 first sentence front-loads the core capability and the rest proceeds in a logical order: what is returned, how results are ranked, then the staleness caveat. It is dense but not padded; the only redundancy is restating the monthly publish cadence and the live:true/API-key condition, which the schema also covers.

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?

An output schema exists, so return values need not be spelled out, and the description nonetheless names the key fields. With a required single key parameter, full schema coverage, and explicit freshness/auth caveats, an agent has everything needed to call this correctly.

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

Parameters3/5

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

Schema coverage is 100%, so every parameter is already documented in the input schema, including the live/_apiKey tradeoff and the naics cross-references. The description adds only the ranking rule for business_name (exact UEI/CAGE/legal-name matches beat fuzzy name hits, active registrations sort above expired), which is a modest but real addition over the schema — baseline 3 is correct given the schema does the heavy lifting.

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 opens with a specific verb and resource — look up federal contractors registered in SAM.gov — and states the three lookup keys (business name, UEI, CAGE). It also enumerates the returned fields and their ranking logic, so an agent knows exactly what this tool answers versus a sibling like sam_search_exclusions or entity_profile.

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

Usage Guidelines4/5

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

It gives a clear rule for the keyless/default path versus live:true, including the condition that selects live (registrations changed since the snapshot) and the cost (10 requests/day on the shared key). It does not explicitly route the agent away from overlapping siblings such as entity_profile or resolve_entity, which keeps it short of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.