> ## Documentation Index
> Fetch the complete documentation index at: https://www.finta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tax tools

> Search tax filings, R&D credits, and 1099 records, or retrieve one by its public ID

After [connecting Finta](/docs/mcp/introduction#connect), your assistant can read tax
filing progress, R\&D credits, and tracked vendor 1099 records with three tools.
Each tool supports both filtered discovery and exact ID retrieval.

| Tool | Reads | Public ID prefix |
| - | - | - |
| `search_taxes` | Income and Delaware franchise filing progress and available PDFs | `tax_income_` or `tax_franchise_` |
| `search_tax_credits` | Federal R\&D credit amounts, their source, and payroll submission status | `tcred_` |
| `search_1099s` | Tracked vendor filing records, annual summaries, and available W-9/1099 documents | `f1099_` |

These tools require **API access: Manage** and **Taxes: View** in the connected
company. OAuth `finta:read` is sufficient. Permissions are checked on each call,
and a public ID cannot select a different company. All three tools are read-only.

Try asking:

* *"Have we filed our 2025 taxes?"*
* *"What is our 2025 R\&D credit, and does payroll submission need action?"*
* *"Which 2025 1099 records still need a W-9?"*

## Search or retrieve by ID

For discovery, omit `id` and pass filters, or pass an empty argument object to
search all available records. Omit `year` to search all available years; there
is no implicit current-year default. Filters combine with AND.

The examples below show the tool name and arguments your MCP client sends.
Your client handles OAuth and the MCP transport.

```json theme={null}
{
  "name": "search_taxes",
  "arguments": { "year": 2025, "status": "review_required", "limit": 25 }
}
```

```json theme={null}
{
  "name": "search_tax_credits",
  "arguments": { "year": 2025, "claim_status": "claimed" }
}
```

```json theme={null}
{
  "name": "search_1099s",
  "arguments": { "year": 2025, "filing_status": "w9_required,w9_requested" }
}
```

To retrieve a known record, pass its public `id` **alone**:

```json theme={null}
{
  "name": "search_1099s",
  "arguments": { "id": "f1099_Example123" }
}
```

An ID combined with any filter or pagination argument is a tool error. Numeric
IDs from the webapp are not accepted; use the public ID returned by the tool.

### Filters

Every tool accepts an exact four-digit `year` from 1000 through 9999, `limit`
(1–500, default 100), and `starting_after` for pagination. The year is the tax
year for filings/credits and the reporting year for 1099s, not submission year.

| Tool | Additional filter | Values and behavior |
| - | - | - |
| `search_taxes` | `type` | `income` or `franchise`. Omit for both. |
| `search_taxes` | `jurisdiction` | `US` for federal, or a supported state code such as `US-CA` or `US-DE`. Matches a code in the record's jurisdictions. |
| `search_taxes` | `status` | `onboarding`, `preparing`, `review_required`, `filing`, or `filed`; filters the returned `filing_status`. |
| `search_tax_credits` | `type` | Currently only `research_and_development`. |
| `search_tax_credits` | `claim_status` | `undecided`, `not_claimed`, `pending`, or `claimed`; concerns the income-tax claim. |
| `search_1099s` | `filing_status` | One or comma-separated stages: `review_required`, `w9_required`, `w9_requested`, `ready_to_file`, `filing`, `filed`, `not_required`. Multiple stages combine with OR. |
| `search_1099s` | `pending` | Boolean. `true` selects `w9_required`, `w9_requested`, `ready_to_file`, and `filing`. `false` selects the other stages, including `review_required` and `not_required`. Omit for both. |
| `search_1099s` | `vendor_name` | Case-insensitive exact display-name match, ignoring surrounding whitespace. No substring search; names can repeat. |
| `search_1099s` | `filed_elsewhere` | Boolean. `true` selects filed records completed outside Finta. `false` selects all other records, including pending ones. Omit for both. |

Use JSON booleans (`true` or `false`), rather than strings. Passing `false` applies
the filter; it is different from omitting the argument.

## Results and pagination

Successful calls include the same JSON in `structuredContent` and a text content
block, with `isError: false`. Both search and ID retrieval return `data`,
`has_more`, and `next_cursor` in a list envelope. An ID lookup returns one record,
`has_more: false`, and `next_cursor: null`. A missing or inaccessible ID is an
error, not an empty successful result.

If `has_more` is true, repeat the same tool and filters, adding the returned
`next_cursor` unchanged as `starting_after`. Never use a record ID as a cursor.
Pagination is live, so records can change between pages. For an invalid or stale
cursor, start a fresh search with the desired filters.

Illustrative exact-ID `structuredContent`, with synthetic IDs and timestamps:

```json theme={null}
{
  "object": "list",
  "url": "/api/v1/forms/1099",
  "data": [
    {
      "id": "f1099_Example123",
      "object": "form_1099",
      "year": 2025,
      "vendor_name": "Example Consulting",
      "filing_status": "w9_requested",
      "filed_at": null,
      "filed_elsewhere": false,
      "documents": [],
      "created": 1769000000,
      "updated": 1769100000
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "summaries": []
}
```

### Annual 1099 summaries

Only `search_1099s` includes `summaries`. Filter searches return complete annual
reports selected by `year`, independent of other filters or pagination.
For example, `pending: true` restricts `data` to pending records, while
`summaries` still counts the year's filed records too. Summaries repeat on each
page; **never add their counts across pages**. Required equals pending plus
filed; review-required records are counted separately.

ID retrieval returns `summaries: []` because no annual summary was requested.
It does not establish zero annual counts. Search by `year` to get the summary.
An absent report is `unknown`; an existing report with no required or unconfirmed
records is `not_required`. These describe tracked records, not legal obligations.
Counts describe filing records, not unique recipients; do not merge records by
vendor name. The [1099 guide](/docs/api-reference/1099-filings#yearly-progress-and-counts)
defines the record and annual-summary stages.

## Interpret progress and amounts

`search_taxes` reads the recorded filing workflow. One income record shares a
filing status across federal and recorded state jurisdictions. Preserve any
`unmapped_jurisdictions`; recognized codes may not cover every recorded state.
`filed` means workflow completion is recorded, without establishing authority
acceptance or payment. Read `filing_status` even when no PDF is available. See
the [filing guide](/docs/api-reference/tax-filings) for status definitions.

`search_tax_credits` returns integer USD cents. Divide by 100 for dollars, and
keep `null` as unknown rather than converting it to zero. State `amount_basis`
when reporting a credit: `estimate`, `prepared_return`, `filed_return`, or null
when unknown. `claimed` describes a positive credit recorded in the filed
income-tax return; `payroll_submission.status` separately describes payroll
submission recorded in Finta. `submitted` does not establish provider acceptance,
and payroll allocation is not a refund received. The [credit guide](/docs/api-reference/tax-credits)
defines the amounts, claim stages, and payroll stages.

Available tax PDFs and W-9/1099 document links expire after five minutes. Retrieve
the record again with `id` alone to refresh them. Keep signed links private.
An empty collection does not establish that a company has no tax obligations.
Treat future unknown status values as unrecognized rather than complete.

## Errors and limits

A business failure returns `isError: true` with text content in the MCP result,
even when the transport returns HTTP 200. API error codes and parameters appear
in that text. They are not a REST error object in `structuredContent`.

| Error | What to do |
| - | - |
| ID combined with other arguments | Pass `id` alone, or omit it and use filters. |
| `invalid_request` | Correct the malformed ID, filter, or pagination argument before retrying. |
| `resource_missing` | Check the public ID and connected company; for a stale cursor, restart the search. |
| `taxes_not_ready` or `forms_not_ready` | Retry later with bounded backoff. Persistent failures need Finta support. |
| `insufficient_permission` | Restore the required company permission; repeated calls will not fix access. |

An expired or revoked OAuth token is a transport authentication failure. Let the
client refresh it, or reconnect. Calls consume the existing [MCP allowance](/docs/mcp/introduction#limits);
the internal API read does not consume an additional API call. Honor rate-limit
retry guidance and wait for the reset or an allowance change after a monthly
limit rejection.

These tools read existing records. They do not calculate or claim credits, file
returns or 1099s, send W-9 requests, or change tax records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.