Tools reference

The deskbird MCP server exposes 4 tools. All of them are read-only, and every request is scoped to the authenticated admin's company on the server side – no tool accepts a company identifier.

Results are returned as JSON in the MCP tool response.

users_list

List all users in the company, with pagination and filters.

Parameter	Type	Description
`offset`	integer, default 0	Pagination offset (0-based)
`limit`	integer, 1–100, default 20	Results per page
`emails`	string[], optional	Filter by email addresses
`providers`	string[], optional	Filter by authentication provider: `Internal`, `Azure`, `Google`, `Okta`, `OneLogin`, `SAML`, `HRIS`, `SCIM`
`statuses`	string[], optional	Filter by account status: `active`, `inactive`, `provisioned`
`userGroupIds`	string[] (UUID), optional	Filter by user group
`primaryOfficeUuids`	string[] (UUID), optional	Filter by primary office

query_analytics

Flexible, composable analytics queries over the company's bookings, scheduling, and utilization tables. Supports selections, filters, grouping, aggregate metrics (for example attendedCount, utilizationPct), ordering, and pagination.

Parameter	Type	Description
`table`	string	Analytics table to query. Get the list from `get_deskbird_docs(resource='catalog')`
`select`	string[]	Columns or aggregate metrics to return, order preserved
`where`	object, optional	Filters keyed by column: scalar shorthand for equals, or operator objects (`eq`, `neq`, `in`, `notIn`, `gt`, `gte`, `lt`, `lte`, `between`, `isNull`, `isNotNull`)
`groupBy`	string[], optional	Group dimensions, required when selecting an aggregate metric
`having`	object, optional	Same shape as `where`, over aggregate metrics that appear in `select`
`orderBy`	object[], optional	`{ column, direction: asc \| desc }`, columns must appear in `select`
`limit` / `offset`	integer, optional	Pagination, capped per table
`includeTotalCount`	boolean, optional	Also return the total row count for the filter
`windowLimit`	object, optional	Top-N rows per partition for grouped queries

The available tables, columns, metrics, and required filters are self-documented: assistants call get_deskbird_docs first to fetch the catalog.

get_resource_hierarchy

Browse the company's offices, floors, and zones one level at a time, optionally with occupancy and utilization stats per child.

Parameter	Type	Description
`scope`	object, default `{ type: 'root' }`	`root` lists offices, `office` (+ `officeUuid`) lists floors, `floor` (+ `floorUuid`) lists zones
`zoneType`	enum, default `flexDesk`	Resource category: `flexDesk`, `meetingRoom`, `parking`, `other`
`metricsStartDate` / `metricsEndDate`	string (YYYY-MM-DD), optional	Provide both to include metrics per child plus a summary; omit both for structure only

get_deskbird_docs

Machine-readable schema documentation for the analytics tools. Assistants call this before querying to learn tables, fields, operators, and metric definitions.

Parameter	Type	Description
`resource`	enum	`catalog` (tables, fields, enums, operators for `query_analytics`), `examples` (worked request examples), `hierarchy` (field docs for `get_resource_hierarchy`)
`table`	string, optional	With `resource='examples'`, filter examples to one table

Limits and errors

Requests are rate limited per user. Assistants should paginate rather than pull full exports.

Invalid parameters return a descriptive validation error in the tool response.

Unexpected server errors return a generic message without internal details.

Expired or invalid tokens return 401 with a WWW-Authenticate challenge; a missing plan feature or role returns 403.

users_list#

query_analytics#

get_resource_hierarchy#

get_deskbird_docs#

Limits and errors#

users_list

query_analytics

get_resource_hierarchy

get_deskbird_docs

Limits and errors