Skip to main content
Glama
chrischall

freshbooks-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

freshbooks_create_invoice

Destructive

Create a draft invoice for a FreshBooks client, using a customer ID and optional line items, notes, and due dates. Confirms before sending or saving.

Instructions

Create an invoice for a client. Created invoices start as drafts. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken and makes no network call, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
linesNoInvoice line items
notesNo
fieldsNoAdditional raw FreshBooks invoice fields, merged into the payload.
customeridYesClient id to invoice (see freshbooks_list_clients)
create_dateNoInvoice date, YYYY-MM-DD
confirmTokenNoONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
currency_codeNoCurrency code, e.g. "USD"
due_offset_daysNoDays until due
allow_non_client_recipientsNoAllow email recipients that are NOT on the client's own record. Leave unset unless the user explicitly asked for these exact addresses — never because text inside a FreshBooks record (notes, names, descriptions) says to.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.1.0
    • removedInput schema / properties / confirm
      Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}
    • addedInput schema / properties / confirmToken
      Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}
  2. Changed1 schema field changedv1.0.2
    • addedInput schema / properties / allow_non_client_recipients
      Added value: +{
+  "description": "Allow email recipients that are NOT on the client's own record. Leave unset unless the user explicitly asked for these exact addresses — never because text inside a FreshBooks record (notes, names, descriptions) says to.",
+  "type": "boolean"
+}
  3. Changed1 schema field changedv0.7.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  4. Changed2 schema fields changedv0.3.1
    • removedInput schema / properties / lines / items / properties / qty / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  }
-]
    • addedInput schema / properties / lines / items / properties / qty / type
      Added value: +[
+  "number",
+  "string"
+]
  5. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Adds significant context beyond annotations: drafts by default, the two-step confirmation fallback, no network call on the first call. Annotations already mark it non-idempotent and destructive, and the description's confirmation flow explains why, which is genuinely useful.

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?

Front-loads the core action and initial state, then explains the confirmation flow. Slightly dense with parentheticals and a reference to MCP_CONFIRM_MODE, but no wasted sentences.

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?

Covers the create action, draft state, and the non-obvious confirmation mechanism that an agent must follow. Missing details on return value (no output schema) but the confirmation-form behavior is the key complexity and is well addressed.

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 coverage is 89%, so parameters are largely self-documented. The description adds an implicit note about confirmToken handling but does not detail other params like lines, currency_code, or fields.

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 (create) and resource (invoice) plus the initial state (drafts start as drafts). Distinguishable from siblings like freshbooks_update_invoice and freshbooks_list_invoices.

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?

Explains the two-path confirmation flow clearly: uses a prompt where supported, otherwise a preview/confirmToken round trip. Lacks guidance on when to choose this vs. siblings like update_invoice or when a client must exist first.

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