Skip to main content
Glama
freshbooks-mcp

freshbooks-mcp

by chrischall

freshbooks_list_invoices

Read-only

List invoices for an authenticated FreshBooks account to see what clients owe, including due dates, statuses, pagination, and filter parameters.

Instructions

List invoices for the authenticated FreshBooks account — what clients owe, with each invoice's due date and status. Supports pagination and raw FreshBooks filter params. Returns items plus page/pages/total; view "brief" returns one line per invoice instead.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "freshbooks_list_invoices"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo1-based page number
viewNo"full" (default) returns FreshBooks' invoices plus page/pages/total; "brief" returns one line per invoice: Invoice <number>, <client>, <amount> — <due date or "no date"> — <status>, inside the untrusted-data envelope as data (client names are third-party text), with "-- " note lines for an empty page ("-- none") or a partial one ("-- N of M shown", "-- more").
searchNoRaw FreshBooks filter params passed through verbatim, e.g. {"search[customerid]": 123} or {"include[]": "lines"}. Field names are not validated.
per_pageNoResults per page (max 100)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.3.1
    • addedInput schema / properties / view
      Added value: +{
      +  "description": "\"full\" (default) returns FreshBooks' invoices plus page/pages/total; \"brief\" returns one line per invoice: Invoice <number>, <client>, <amount> — <due date or \"no date\"> — <status>, inside the untrusted-data envelope as data (client names are third-party text), with \"-- \" note lines for an empty page (\"-- none\") or a partial one (\"-- N of M shown\", \"-- more\").",
      +  "enum": [
      +    "full",
      +    "brief"
      +  ],
      +  "type": "string"
      +}
  2. 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"
  3. Changed2 schema fields changedv0.3.1
    • removedInput schema / properties / search / additionalProperties / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "boolean"
      -  }
      -]
    • addedInput schema / properties / search / additionalProperties / type
      Added value: +[
      +  "string",
      +  "number",
      +  "boolean"
      +]
  4. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already cover readOnlyHint and openWorldHint, but the description goes further: it discloses the return shape ("items plus page/pages/total"), explains that brief output sits "inside the untrusted-data envelope as data" with client names as third-party text, and documents empty/partial-page note lines. That is real behavioral context an agent would otherwise have to discover empirically, though nothing is said about rate limits or auth requirements.

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?

Two dense sentences, front-loaded with purpose and scope before the pagination and view details. Some of the brief-view note-line detail duplicates the schema's view description, which is slight redundancy, but nothing is padded or meandering.

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?

With no output schema, the description carries the return-value burden and does so: it names the payload fields, the pagination envelope, and the brief-view line format including edge cases. Combined with annotations covering safety, an agent has enough to call this correctly without further probing.

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 the schema already defines page, per_page, view, and the raw search object with examples. The description restates the same facts (pagination, raw FreshBooks filter params, brief view) without adding format or constraint detail beyond the schema, which is the expected baseline when structured fields carry the load.

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?

The description opens with a specific verb+resource ("List invoices for the authenticated FreshBooks account") and adds domain framing ("what clients owe, with each invoice's due date and status"). It is clearly distinct from freshbooks_get_invoice, but it never names that sibling or states the list-vs-single distinction explicitly, so differentiation is inferred rather than stated.

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?

It gives an implied selection rule by contrasting views ("view 'brief' returns one line per invoice instead"), which tells an agent when to prefer brief over full. However, there is no explicit guidance on when to use this tool versus freshbooks_get_invoice or how to scope results with filters; usage must be inferred from the phrasing.

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