search_contracts

Search federal contract awards by agency, vendor, NAICS code, or keyword to find award details including value, performance period, and competition type.

Instructions

Search federal contract awards by agency, vendor, NAICS code, or keyword. Returns award details including value, period of performance, and competition type. Cost: $0.018 per query. Source: USAspending.gov, updated daily.

Input Schema

TableJSON Schema

Name	Required	Description
`agency`	No	Awarding agency name or abbreviation (e.g. DOD, HHS)
`vendor`	No	Vendor/contractor name (partial match)
`naics`	No	NAICS code filter
`keyword`	No	Keyword search in award description
`min_value`	No	Minimum award value in USD
`limit`	No	Maximum results (default 25)

Implementation Reference

src/tools/contracts.ts:69-99 (handler)

The handler function for the `search_contracts` tool, which fetches data from the API based on provided filter parameters.

async ({ agency, vendor, naics, keyword, min_value, limit }) => {
  const res = await apiGet<ContractQueryResponse>("/api/v1/contracts", {
    agency,
    vendor,
    naics,
    keyword,
    min_value,
    limit: limit ?? 25,
  });

  if (!res.ok) {
    return {
      content: [
        {
          type: "text" as const,
          text: `API error (${res.status}): ${JSON.stringify(res.data)}`,
        },
      ],
      isError: true,
    };
  }

  const { count, data } = res.data;
  const warn = stalenessWarning(res);
  const summary = `${warn}Found ${count} contract award(s).`;
  const json = JSON.stringify(data, null, 2);

  return {
    content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
  };
},

src/tools/contracts.ts:39-67 (schema)

The input schema validation using Zod for the `search_contracts` tool parameters.

inputSchema: {
  agency: z
    .string()
    .optional()
    .describe("Awarding agency name or abbreviation (e.g. DOD, HHS)"),
  vendor: z
    .string()
    .optional()
    .describe("Vendor/contractor name (partial match)"),
  naics: z
    .string()
    .optional()
    .describe("NAICS code filter"),
  keyword: z
    .string()
    .optional()
    .describe("Keyword search in award description"),
  min_value: z
    .number()
    .optional()
    .describe("Minimum award value in USD"),
  limit: z
    .number()
    .int()
    .min(1)
    .max(100)
    .optional()
    .describe("Maximum results (default 25)"),
},

src/tools/contracts.ts:31-100 (registration)

Registration of the `search_contracts` tool within the MCP server using server.registerTool.

server.registerTool(
  "search_contracts",
  {
    title: "Search Government Contracts",
    description:
      "Search federal contract awards by agency, vendor, NAICS code, or keyword. " +
      "Returns award details including value, period of performance, and competition type. " +
      "Cost: $0.018 per query. Source: USAspending.gov, updated daily.",
    inputSchema: {
      agency: z
        .string()
        .optional()
        .describe("Awarding agency name or abbreviation (e.g. DOD, HHS)"),
      vendor: z
        .string()
        .optional()
        .describe("Vendor/contractor name (partial match)"),
      naics: z
        .string()
        .optional()
        .describe("NAICS code filter"),
      keyword: z
        .string()
        .optional()
        .describe("Keyword search in award description"),
      min_value: z
        .number()
        .optional()
        .describe("Minimum award value in USD"),
      limit: z
        .number()
        .int()
        .min(1)
        .max(100)
        .optional()
        .describe("Maximum results (default 25)"),
    },
  },
  async ({ agency, vendor, naics, keyword, min_value, limit }) => {
    const res = await apiGet<ContractQueryResponse>("/api/v1/contracts", {
      agency,
      vendor,
      naics,
      keyword,
      min_value,
      limit: limit ?? 25,
    });

    if (!res.ok) {
      return {
        content: [
          {
            type: "text" as const,
            text: `API error (${res.status}): ${JSON.stringify(res.data)}`,
          },
        ],
        isError: true,
      };
    }

    const { count, data } = res.data;
    const warn = stalenessWarning(res);
    const summary = `${warn}Found ${count} contract award(s).`;
    const json = JSON.stringify(data, null, 2);

    return {
      content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
    };
  },
);

Verilex Data