APIbase

Search CFPB Consumer Complaints

cfpb-complaints.complaints.search

Read-onlyIdempotent

Search CFPB public consumer complaints by product, company, state, issue, response, date range, or narrative text to retrieve complaint records and company responses.

Instructions

Search the US Consumer Financial Protection Bureau public complaint database of 17M+ consumer complaints against financial companies (banks, credit reporting agencies, debt collectors, lenders). Filter by product, company, US state, issue, company response, timeliness, whether a narrative was provided, and date range, or full-text search consumer narratives. Returns complaint records with product/issue category, company, state, dates, and company response. Data: consumerfinance.gov (CFPB), no auth required.

Input Schema

Name	Required	Description
`frm`	No	Offset for pagination, i.e. skip this many results (default 0).
`size`	No	Number of complaints to return, 1-100 (default 10).
`sort`	No	Result ordering (default "created_date_desc").
`field`	No	Which field `search_term` searches: "complaint_what_happened" (consumer narrative text, default) or "all" (all indexed text fields).
`issue`	No	Exact CFPB issue category — must match verbatim, e.g. "Incorrect information on your report", "Attempts to collect debt not owed", "Managing an account", "Written notification about debt". A near-miss silently returns 0 results rather than an error.
`state`	No	Two-letter US state or territory postal abbreviation (e.g. "CA", "NY", "PR").
`timely`	No	Whether the company responded to the complaint in a timely manner.
`company`	No	Exact registered company name as CFPB records it, typically uppercase with legal suffix (e.g. "EQUIFAX, INC.", "WELLS FARGO & COMPANY", "BANK OF AMERICA, NATIONAL ASSOCIATION"). A near-miss silently returns 0 results rather than an error.
`product`	No	Exact CFPB product category — must match verbatim, e.g. "Credit reporting or other personal consumer reports", "Debt collection", "Mortgage", "Checking or savings account", "Credit card", "Credit card or prepaid card", "Money transfer, virtual currency, or money service", "Student loan", "Vehicle loan or lease", "Payday loan, title loan, personal loan, or advance loan", "Prepaid card". A near-miss (e.g. wrong wording) silently returns 0 results rather than an error.
`search_term`	No	Full-text search query (e.g. "overdraft fee", "credit report error"). Searched against the field named by `field`.
`has_narrative`	No	Only return complaints that include (true) or omit (false) a consumer narrative.
`company_response`	No	How the company responded to the complaint.
`date_received_max`	No	Only complaints received on/before this date, format YYYY-MM-DD.
`date_received_min`	No	Only complaints received on/after this date, format YYYY-MM-DD.

Output Schema

Name	Required	Description	Default
`error`	No	Present only when the call failed. Includes error code, message, request_id, and any provider-specific extras.
`result`	No	Tool response payload. Shape varies per tool — consult the tool description and inputSchema. May be an object, array, string, or number depending on the upstream provider response.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.2.0Oct 29, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond those annotations: the data source ('consumerfinance.gov (CFPB)') and that no authentication is required. It does not contradict any annotation.

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 compact and front-loaded: purpose first, then filters, then return shape, then source/auth. Each sentence contributes useful information, though the filter list somewhat duplicates the schema and the provenance sentence is repeated in spirit by the first sentence.

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?

Given a fully documented 14-parameter schema with 100% coverage, a rich output schema, and complete safety annotations, the description provides enough high-level context—data source, auth requirement, filter capabilities, and return contents—for an agent to select and invoke the tool 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 description coverage is 100%, so the baseline is 3. The description paraphrases several filter dimensions (product, company, state, issue, date range, narrative) and mentions full-text narrative search, which helps orient the agent, but it does not add meaning beyond what the input schema already provides in detail.

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

Purpose4/5

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

The description uses a specific verb and resource: 'Search the US Consumer Financial Protection Bureau public complaint database' and states what it returns ('complaint records with product/issue category, company, state, dates, and company response'). It clearly identifies the tool's function, though it does not explicitly differentiate it from sibling tools like cfpb-complaints.complaints.by_state or cfpb-complaints.complaints.trends.

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?

The description gives clear context for when to use the tool: filtering by product, company, state, issue, response, timeliness, narrative presence, and date range, or full-text searching narratives. It does not explicitly mention when not to use it or route to the by_state/trends alternatives, so it stops short of full alternative guidance.

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

Deploy Server