Tradify MCP Server and API by Cotlet

Create invoice

create_invoice

Destructive

Draft invoice with its own line items, on a job or a customer. Nothing is sent until send_invoice. Creates a draft miscellaneous invoice, as New Invoice > Miscellaneous does, for a customer and optionally one of their jobs (job_id); no quote needed (for that, create_invoice_from_quote). Each line is misc (description, quantity, unit_price), time (hours at a billing rate) or price_list (item_code of a price list item); time and price list lines take the customer's price group price unless unit_price is given. Tax uses the default rate (a price list item's own rate), or tax_rate by name; tax_inclusive says whether prices include tax (default exclusive, or the job's setting). Reference and description default to the job's. theme picks a theme by name; terms sets the invoice terms (default the theme's). The due date follows the payment terms unless due_date is given. Kits are not supported. The invoice stays a draft until send_invoice.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "customer_id": "<customer_id>",
      "line_items": "<line_items>"
    },
    "name": "create_invoice"
  }
}

Input Schema

Name	Required	Description
`terms`	No	Invoice terms. Default: the theme's invoice terms.
`theme`	No	Theme name (Settings > Themes). Default: the customer's.
`job_id`	No	Invoice this customer's job (list_jobs).
`due_date`	No	Default: the payment terms.
`reference`	No	Customer reference. Default: the job's.
`line_items`	Yes
`customer_id`	Yes	From list_customers or get_job.
`description`	No	Shown on the invoice. Default: the job's.
`invoice_date`	No	Default: today.
`tax_inclusive`	No	Prices include tax. Default: the job's or customer's setting (tax exclusive).

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 5, 2026

TDQS

A4.5/5.0

Behavior4/5

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

The annotations already declare non-read-only, open-world, non-idempotent, and destructive behavior. The description adds important lifecycle context: the tool only creates a draft, sends nothing until send_invoice, and keeps the invoice as a draft, along with default inheritance rules and unsupported kits. The destructiveHint=true is not directly explained, but the draft/no-send framing does not contradict it.

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 purpose and draft-safety constraint are front-loaded, and the dense line-item rules are appropriate for a 10-parameter create tool. There is some repetition of the draft/not-sent status across the opening and closing sentences, which costs a little conciseness.

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

Completeness4/5

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

With no output schema, the description still covers the key lifecycle and call semantics: draft-only creation, no sending until send_invoice, line-item types, tax behavior, and default inheritance. It does not explicitly describe the return value, such as whether an invoice ID is returned, but the critical invocation behavior is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 90%, so the schema already documents most parameters. The description adds meaningful cross-field semantics: time and price_list lines use the customer's price group price unless unit_price is supplied, tax defaults to the price list item's rate or tax_rate by name, and due_date/reference/description inherit job/theme/payment-term defaults. It does not restate every schema detail, such as invoice_date defaulting to today, but it adds real meaning beyond the schema.

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?

The description uses a specific verb and resource: it creates a draft invoice with its own line items for a customer and optionally a job. It explicitly distinguishes this from create_invoice_from_quote and send_invoice, so an agent can select the right tool without opening the 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?

It states when to use this tool: no quote is needed, and the invoice is built directly for a customer/job. It names the alternative create_invoice_from_quote for quote-based invoices and clarifies that nothing is sent until send_invoice, plus explicitly notes that kits are not supported.

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

All Tradify MCP Server and API by Cotlet 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.