Fresha MCP Server and API by Cotlet

List appointments

list_appointments

Read-onlyIdempotent

Appointments in a date range, with client, service, team member, price and status. Lists appointments that start between from and to (both days included; from defaults to today, to to from) as Sales > Appointments shows them, latest first: one row per booked service with its appointment id, reference, start (wall clock in the business's time zone), length, client, team member, price, status and channel (online or offline). Cancelled appointments are included with their status. location_id keeps one location of a business with several. Page with next_cursor. The report itself has no status, team member or client filter, so those three apply to the first 100 rows of the date range: for a busy range, narrow the dates.

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": "list_appointments"
  }
}

Input Schema

Name	Required	Description
`to`	No	Last day of the range, included. Default: same as from.
`from`	No	First day of the range (the day appointments start, YYYY-MM-DD). Default: today in the business's time zone.
`limit`	No	Page size. Default: 50.
`cursor`	No	next_cursor from the previous call.
`status`	No	Only this status, as Fresha names it: booked, confirmed, arrived, started, completed, canceled, no-show. Default: all.
`client_id`	No	Only this client's appointments.
`location_id`	No	Only appointments at this location. Default: all.
`team_member_id`	No	Only this team member's appointments.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 31, 2026

changedInput schema / properties / from / description

Previous value: -"First day."New value: +"First day of the range (the day appointments start, YYYY-MM-DD). Default: today in the business's time zone."

addedInput schema / properties / location_id

Added value: +{
+  "description": "Only appointments at this location. Default: all.",
+  "pattern": "^[0-9]+$",
+  "type": "string"
+}

changedInput schema / properties / to / description

Previous value: -"Last day. Default: same as from."New value: +"Last day of the range, included. Default: same as from."

removedInput schema / required
```
Removed value: -[
-  "from"
-]
```

First observedOct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

The description adds substantial behavior beyond the annotations: cancelled appointments are included, rows are ordered latest first, one row represents one booked service, times are wall-clock in the business time zone, and the filter caveat is disclosed. These details help an agent predict results and avoid misusing filters on busy date ranges.

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 description is front-loaded with the resource and scope, and most sentences carry useful operational detail. It is somewhat dense and repeats the list of returned fields, but the length is largely justified by the tool's filtering and pagination caveats.

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 well by listing the fields in each row, the ordering, the one-row-per-booked-service behavior, and pagination via next_cursor. It also covers defaults, date-range semantics, location scoping and the report's filter limitation, leaving no major gap for correct invocation.

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 coverage is 100%, so the schema already documents all eight parameters. The description still adds meaningful semantics, especially the inclusive date range, to defaulting to from, location_id behavior, next_cursor pagination, and the critical note that status, team_member_id and client_id only apply to the first 100 rows.

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 states a specific verb and resource: it lists appointments in a date range and explains the row shape, including appointment id, reference, start, length, client, team member, price, status and channel. This clearly distinguishes it from siblings like get_appointment, list_sales and find_available_slots.

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?

It gives clear usage context, including defaults for from and to, pagination via next_cursor, and the important limitation that status, team member and client filters only apply to the first 100 rows of the date range. It does not explicitly name an alternative sibling tool for fetching a single appointment or for applying full-range filters, so it falls short of a full 5.

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

All Fresha 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.