Tools

Generated from tools/list of a running host; the census test pins the same surface. Eight tools in four families, listed in the order the server returns them. Every result is JSON text under 20 KB; errors come back as results with isError: true carrying the API’s envelope (status, error.code, error.message).

Family	Tool	Title	Hints
Discovery	exonaut_status	Status	read-only, idempotent
Discovery	exonaut_search_entities	Search entity sets	read-only, idempotent
Discovery	exonaut_describe	Describe an entity set or route	read-only, idempotent
Read	exonaut_query	Query a collection	read-only, idempotent
Read	exonaut_get	Get one entity	read-only, idempotent
Change	exonaut_preview_change	Preview a change (dryRun)	read-only, idempotent
Change	exonaut_apply_change	Apply a previously previewed change	destructive
Help	exonaut_explain_error	Explain an error	read-only, idempotent

exonaut_status

Discovery family: reports this exonaut host: build version, licence plan, whether MCP writes are enabled, the REST base URL, readiness of the Exchange Online connection, and the size of the surface (live entity sets and documented routes). Call it first to learn what this host can do. No arguments. Available on every plan.

No arguments.

exonaut_search_entities

Discovery family: finds the entity sets (REST collections) that match a word, a label or an Exchange Online cmdlet name, for example “shared mailbox”, “retention” or “Get-DistributionGroupMember”. Each match carries the entity set to use in paths, its category, the read and write roles a token needs, the plan that unlocks its writes, and how many routes it has. Use it before exonaut_describe when you do not know the entity set name. Returns at most top matches (default 20) and says whether more exist.

Argument	Type	Required	Description
query	string	yes	A word, a label or a cmdlet name, 1 to 100 characters, matched case-insensitively against entity set names, labels, categories and backing cmdlets.
top	integer	no	Maximum matches to return, 1 to 200; default 20.

exonaut_describe

Discovery family: describes every route of an entity set, or one route. Pass entitySet (for example “distributionGroups”) or route (for example “POST /exchange/v1.0/distributionGroups”). Each route lists its synopsis, parameters (name, where it goes, required, type), the role a token needs, the plan that unlocks it, the backing Exchange Online cmdlet and its Microsoft Learn page, plus up to two short worked examples. Use it before exonaut_query, exonaut_get or exonaut_preview_change to get paths, fields and bodies right.

Argument	Type	Required	Description
entitySet	string	no	The entity set name as returned by exonaut_search_entities, for example mailboxes.
route	string	no	One route as “VERB /exchange/v1.0/path”, for example “GET /exchange/v1.0/mailboxes”.

exonaut_query

Read family: reads a collection with OData options, for example path “mailboxes” with filter “RecipientTypeDetails eq ‘SharedMailbox’”, select [“DisplayName”,“PrimarySmtpAddress”], orderby “DisplayName”, top 25. The path is an entity path under exchange/v1.0/ without a leading slash; sub-resources work too (“mailboxes/[email protected]/permissions”). Returns items, count, truncated and, when more exist, nextLink and nextSkip to pass back as skip. top defaults to 50 and is capped by the host. Results are trimmed to the selected fields and kept under 20 KB. A failing route answers as an error carrying the API’s envelope (status, error.code, error.message).

Argument	Type	Required	Description
path	string	yes	Entity path under exchange/v1.0/, no leading slash, for example mailboxes or distributionGroups/[email protected]/members.
filter	string	no	OData $filter expression, for example RecipientTypeDetails eq ‘SharedMailbox’.
select	array of string	no	Fields to return, for example [“DisplayName”,“PrimarySmtpAddress”]; unselected fields are dropped.
orderby	string	no	OData $orderby, for example DisplayName desc.
top	integer	no	Page size, 1 to the host’s maximum (200 by default); default 50.
skip	integer	no	Items to skip; pass the previous result’s nextSkip to page.

exonaut_get

Read family: reads one entity by its path with a key, for example “mailboxes/[email protected]” or “distributionGroups/[email protected]”; keys accept whatever the cmdlet’s Identity accepts (UPN, alias, primary SMTP, GUID, display name). select trims the answer to the named fields. Returns the entity JSON; a missing entity answers as an error with the API’s 404 envelope. Results are kept under 20 KB.

Argument	Type	Required	Description
path	string	yes	Entity path with its key under exchange/v1.0/, no leading slash, for example mailboxes/[email protected].
select	array of string	no	Fields to return, for example [“DisplayName”,“HiddenFromAddressListsEnabled”].

exonaut_preview_change

Change family: previews a write without making it. Pass method (POST, PATCH or DELETE), path (an entity path under exchange/v1.0/, for example distributionGroups/[email protected]/members/$ref) and body (the JSON the route takes; exonaut_describe shows the fields). The route runs with ?dryRun=true, so nothing changes. The answer carries the preview (the cmdlet’s WhatIf output when it has one), the plan the route needs, and a confirmationToken that exonaut_apply_change replays once, within 20 minutes, for the same caller and the same method, path and body. Enterprise-tier routes answer RestOnly with the REST path to use instead; a cmdlet whose dry run is a no-op answers DryRunUnsupported, also with the REST path.

Argument	Type	Required	Description
method	string	yes	POST, PATCH or DELETE.
path	string	yes	Entity path under exchange/v1.0/, no leading slash, with the key where the route has one.
body	JSON	no	The request body as JSON; omit for DELETE and for routes without a body.

exonaut_apply_change

Change family: makes the change that exonaut_preview_change previewed, by replaying exactly its method, path and body. Pass the confirmationToken from the preview: it works once, expires 20 minutes after the preview and only for the caller who previewed. Optionally pass method, path and body again to assert what will be applied; any difference answers TokenMismatch and discards the token. Needs Mcp:AllowWrites=true on the host, else WritesDisabled. Returns the route’s answer: the created or updated entity, or status 204.

Argument	Type	Required	Description
confirmationToken	string	yes	The confirmationToken returned by exonaut_preview_change.
method	string	no	Optional: the method you expect to apply; must equal the previewed one.
path	string	no	Optional: the path you expect to apply; must equal the previewed one.
body	JSON	no	Optional: the body you expect to apply; must equal the previewed one.

exonaut_explain_error

Help family: explains an error the API returned. Pass the envelope another tool returned (status plus error.code and error.message) or just the code, for example Conflict, Forbidden, NotFound, UnprocessableEntity or TooManyRequests. Answers the status, the catalogue’s description of when it happens, concrete next actions and the documentation URL.

Argument	Type	Required	Description
envelope	JSON	no	The error envelope as a tool returned it: { status, error: { code, message, target, details } }.
code	string	no	The error code alone, for example Conflict.