Skip to main content
Glama
klodr

mercury-invoicing-mcp

by klodr
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

mercury_create_customer

Create a new Accounts Receivable customer (a billable entity you will later invoice).

Instructions

Create a new Accounts Receivable customer (a billable entity you will later invoice).

USE WHEN: onboarding a new customer before issuing them an invoice. The returned id is what mercury_create_invoice expects as customerId.

DO NOT USE: for payment recipients (use mercury_add_recipient — different surface, used for outbound bank transfers, not invoicing).

SIDE EFFECTS: writes a new customer to your Mercury workspace. Persistent. NOT idempotent at the API level — calling twice with the same payload creates two customers; check mercury_list_customers for existing entries before creating to avoid duplicates.

RETURNS: { id, name, email, address, ... } — keep id for the invoicing tools.

Input Schema

NameRequiredDescriptionDefault
nameYesCustomer name
emailYesCustomer email
addressNoCustomer billing address (Mercury requires `name` in the address)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.20.3
    • changedInput schema / properties / email / pattern
      Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
  2. Addedv0.15.6
  3. Removedv0.15.5
  4. Addedv0.15.4
  5. Removedv0.15.2
  6. Changed1 schema field changedv0.12.0
    • addedInput schema / additionalProperties
      Added value: +false
  7. First observedv0.9.1

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only give openWorldHint and destructiveHint=false, so the description carries the real burden: it discloses that this is a persistent write, that it is NOT idempotent at the API level, and that duplicate payloads create two customers. That non-idempotency warning is substantive behavioral context an agent cannot infer from 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Labeled sections (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) keep the important constraints front-loaded, and every sentence carries a distinct fact. Length is justified by the duplicate-creation risk it must prevent.

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?

No output schema exists, and the description compensates by sketching the return shape ({ id, name, email, address, ... }) and telling the agent to retain the id for downstream invoicing tools. With required params, side effects, alternatives, and return value all covered, nothing an agent needs is missing.

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%, including the nested address object and its required fields, so the baseline applies. The description adds no field-level meaning beyond confirming the returned id maps to customerId on mercury_create_invoice; it does not clarify why name/email are required or how address is used.

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?

States a specific verb+resource ('Create a new Accounts Receivable customer') and immediately disambiguates the confusing sibling by defining the entity as 'a billable entity you will later invoice' versus a payment recipient. An agent can tell this apart from mercury_add_recipient without opening either schema.

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

Usage Guidelines5/5

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

Explicit USE WHEN (onboarding a customer before invoicing) and an explicit DO NOT USE that names the alternative tool and explains why the surfaces differ ('outbound bank transfers, not invoicing'). It also prescribes a pre-check against mercury_list_customers to avoid duplicates.

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

Deploy Server

Other Tools