Mercoa MCP by usefulapi

Find invoices

mercoa_find_invoices

Read-only

Find/search invoices (bills) across payers and vendors. Filter by status, entity, date, approver and more. GET /invoices (plural list endpoint).

Input Schema

Name	Required	Description
`limit`	No	Max invoices to return (1-100, default 10).
`search`	No	Search by vendor name, invoice number, check number, or amount.
`status`	No	Invoice status filter (e.g. DRAFT, NEW, APPROVED, SCHEDULED, PAID).
`endDate`	No	End date filter (ISO 8601).
`orderBy`	No	Field to order by (e.g. CREATED_AT, AMOUNT, DUE_DATE).
`payerId`	No	Filter by payer ID(s) or foreign ID(s).
`dateType`	No	Date type to filter by (e.g. CREATED_AT, DUE_DATE).
`entityId`	No	Filter by entity (payer or vendor) ID(s) or foreign ID(s).
`vendorId`	No	Filter by vendor ID(s) or foreign ID(s).
`invoiceId`	No	Filter by invoice ID(s) or foreign ID(s).
`startDate`	No	Start date filter (ISO 8601).
`approverId`	No	Filter by assigned approver user ID(s).
`paymentType`	No	Filter by payment type (e.g. recurring).
`creatorUserId`	No	Filter by the user ID(s) that created the invoice.
`entityGroupId`	No	Filter by entity group ID.
`startingAfter`	No	Invoice ID cursor for pagination.
`approverAction`	No	Filter by approver action (use with approverId), e.g. APPROVE.
`orderDirection`	No	asc or desc.
`invoiceTemplateId`	No	Filter by invoice template ID(s).
`returnPayerMetadata`	No	Include payer metadata in the response.
`returnPaymentTiming`	No	Include payment timing in the response.
`returnVendorMetadata`	No	Include vendor metadata in the response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 9, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

First observedJul 18, 2026

TDQS

B3.4/5.0

Behavior3/5

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

readOnlyHint=true already tells the agent this is a non-mutating read, so the safety burden is lifted. The description adds only the underlying GET endpoint and a vague 'and more' on filters; it says nothing about pagination behavior, default limits, or that the returnPayerMetadata/returnVendorMetadata flags inflate the payload.

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?

Three short sentences, front-loaded with the core purpose and no redundancy. The endpoint fragment is arguably skippable, but it does double as disambiguation against the singular get tool, so it mostly earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 22-parameter search tool with no output schema, the description is thin on return-shape and pagination expectations, though the 100% schema coverage carries the parameter burden. It is adequate for calling the tool but leaves the agent guessing about result volume and cursor semantics.

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 all 22 parameters are already documented with formats, defaults, and examples. The description's filter list merely echoes a subset of what the schema already provides and adds no syntax, precedence, or combination guidance.

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?

States a specific verb (find/search) and resource (invoices), and parenthetically clarifies it is the plural list endpoint, which implicitly distinguishes it from the singular mercoa_get_invoice sibling. Scope ('across payers and vendors') and the supported filter families are named, though no sibling is called out by name.

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

Usage Guidelines3/5

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

The description implies usage by listing filter dimensions (status, entity, date, approver), so an agent can infer it is the batch/discovery tool. However, it never states when to prefer this over mercoa_get_invoice for a single record, nor when to use it versus mercoa_find_transactions or the entity-scoped list tools.

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

All Mercoa MCP by usefulapi tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Find invoices

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources