Nestr

Create a new workspace. Auth: OAuth only (user-scoped — workspace API keys cannot create new workspaces). On auth failure call nestr_diagnose. See nestr_help('workspace-setup') for guided setup.

Delete a comment (soft delete).

Delete a file attachment from a nest (or comment). Get the file id from nestr_get_nest_files. A comment ID works as the nestId. This permanently removes the file. Auth: a token with delete access to the nest.

Delete a nest. For governance items in established workspaces, use tensions instead. On a recurring item this deletes only that one nest and never ends the series: deleting an occurrence skips it, and deleting the series nest hands the series to its next occurrence, which carries on as the series. To skip an occurrence use nestr_skip_occurrence, to delete it and every later one use nestr_skip_occurrence with scope 'following', and to delete the whole series use nestr_delete_series. The delete is checked against the rights of the person behind the token, including a workspace-bound OAuth or age…

Delete a whole recurring series: the series nest and every occurrence, past ones included. Use only when the series and its history should go. To stop repeating but keep the nests, use nestr_set_recurrence with rrule: null. To skip one occurrence, or remove one and every later one while keeping history, use nestr_skip_occurrence. Answers with `restoreId`, the series nest: restoring it in the Nestr app brings back that nest only, and the occurrences deleted with it are restored separately. Needs delete rights on the series and on every occurrence it removes, and a refusal writes nothing. Refuse…

Delete a tension (soft delete).

Soft-delete an accountability or domain from a proposal part. When the proposal is enacted, the original accountability/domain is removed from the role.

Server-side auth and session diagnostics. Call this FIRST when any other tool returns an auth error (AUTH_TOKEN_REJECTED_BY_NESTR / AUTH_REFRESH_FAILED / AUTH_SCOPE_INSUFFICIENT / AUTH_PROXY_HEADER_DROPPED). Returns: flow (A=server-managed refresh, B=client-managed refresh, unknown=API key), tokenPresented, tokenFingerprint, lastUpstream401At, lastRefreshAttempt, sessionCorrelationId, serverVersion, mcpClient, mcpClientVersion. Auth: none required — works whether or not the bearer is valid.

Bring a human from Nestr support into a Nestradamus conversation. Use it when the person asks for a human, when you have answered the wrong question more than once, or when something needs Nestr staff to look at their account. Find the thread with nestr_list_dms({withUser:'nestr_support'}). Safe to call twice; a thread already waiting stays as it is. Only works on a conversation Nestradamus is in.

Diagnose a single nest: WHY it looks and behaves as it does. Returns field/property provenance (which label and circle defines each field, value, and property such as the icon), the caller's composed rights with a deny trace (why a field is read-only, why you cannot edit), and — when whoCan is given — who can perform an op and who to contact. Use this when a user asks 'why can't I ...', 'why is this read-only', 'where does this field come from', 'why does this role have a different icon', or 'who can change this'. When a role connector is held back on scheduled runs pending approval of the rol…

What an agent can and cannot use, and why. Groups each connector by where the grant comes from (its own binding, the workspace, or a role it fills) and, when unavailable, names the reason: no credential yet, the connector is disabled, it has no usable tools, or it no longer allows this kind of access. Reach for this when an agent seems to be missing something it should have.

How one agent operates on one nest: reactive (acts when mentioned, messaged or handed work) or autonomous on a cadence. `recheck` is "continuous" or an RRULE; `start` and `tzid` anchor it and `nextRunAt` is when it fires next. The mode is always per nest, never a setting of the agent as a whole, and items inherit it from their role or circle unless they set their own. `source` says which: own, inherited, or default.

Get details of a specific circle including purpose, domains, and accountabilities.

Get all roles within a specific circle, including accountabilities. Response includes meta.total showing total matching count.

Get comments and discussion history on a nest, including full nested reply threads. By default returns only comments posted directly on the given nest. Widen with depth to also include comments on descendant nests, or pass a workspace/circle nest ID with depth='all' to gather large sets of communication for analysis. Carries an unread_posts hint when you have not read everything; nestr_mark_post_read acknowledges up to a given post, on any nest, not just direct messages.

Get a link a PERSON opens to connect an account for a binding. This is how you finish setting up access: you can register a connector and give a role access, but you must never handle a raw token, so the sign-in or key entry happens behind this link. The link carries no authority — whoever opens it is checked then. Give it to the user in your reply.

Get the user's daily plan — items marked for today. Spans all workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Read the posts in a direct-message thread, oldest first, each with its nested replies. Pass unread:true for just what is new, false for the rest.

Get a direct-message thread as a nest, with hints. Pass unread:true to embed the posts you have not read in the same call, which is usually what you want when picking a thread back up.

Get nests linked via a named graph relation. Links are directed: each row says whether it is outgoing (this nest links to it) or incoming (it links to this nest). Use 'meeting' relation to get agenda items or linked meetings. For Timeline dependencies use 'depends_on': outgoing are the predecessors this nest waits for, incoming are the nests waiting on it.

Get details of a specific inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Get a single metric with its current and compare values. Use after nestr_get_insights to drill into a specific metric. Requires the Insights app to be enabled.

Get historical data points for a metric over time. Use from/to for date range. Requires Insights app.

Get organizational health metrics and trends. Each metric has currentValue and compareValue for direction. Pro plan: filter by circle (nestId) or user (userId). Requires Insights app. See nestr_help('insights').

Get details of a specific label, including fields, properties, group and autoComplete. `autoComplete: false` marks a system label: it is withheld from the label picker, and an already-applied one is hidden from the label tags on the nest too, so the person cannot see it in either place. Do not suggest such a label to a user, apply it as if they had chosen it, or tell them to click it on an item, because there is nothing there to click. It is not unreachable though: typing the id verbatim in the add/remove label modal still matches it, and a `label:` search on the id still finds the items carry…

CALL THIS FIRST at session start. Returns identity, operating mode, and workspaces. Use fullWorkspaces:true to include workspace details.

Get nest details. Supports comma-separated IDs for batch fetch. Add hints=true for contextual signals, fieldsMetaData=true for the declared field schema of every label on the nest, including fields with no value. For a single nest you can also diagnose it: provenance, rights, and whoCan (see explain_nest for a one-shot diagnosis). The users array holds user ids; when presenting to a person, resolve them to names and/or emails via nestr_get_user or nestr_list_users.

What happened on a nest and, by default, everything beneath it, newest first: the Activity tab over the API. Each entry carries who did it (userId, agentUserId when an assistant acted), the sentence the app shows, and the same change as data in `changes`: one row per field with its value before and after, named as nestr_get_nest names them (title, users, parentId, data.<key>, fields.<label>.<code>). Agent runs appear as considerations with their summary, tools and outcome. Use depth to narrow (0 for the nest alone, N for N levels) and userId for one person's work. Paging is by cursor: read `ha…

Get children of a nest, or just the ones you want. Pass `search` with the full operator syntax to ask for a subset rather than fetching everything and filtering: `search: 'label:role'` returns a circle's roles in one call. Paginated at 50 per page; read meta.total for the match count. Rows leave out text tab bodies (`fields` keys ending in `_texttab`); read those with nestr_get_nest.

List a nest's file attachments. Images pasted into the nest's text are deliberately excluded — they belong to the text that references them; the inline_images hint counts those and their ids come from the references in the content. A comment ID works too — files are keyed by nestId, so pass a comment ID to see files attached to that comment. Returns each file's id, name, contentType and size. Use nestr_read_file with a returned id to read one (JPEG/PNG/GIF/WebP come back as viewable image content; SVG comes back as its markup). Auth: any valid token with access to the nest.

List all projects in a workspace. Check fields['project.status'] for status (Future/Current/Waiting/Done). Paginated. Rows leave out text tab bodies (`fields` keys ending in `_texttab`); read those with nestr_get_nest.

Get a single tension with its current status. Use nestr_get_tension_status for per-user voting details.

Get the diff for a proposal part showing what will change (oldValue vs newValue).

List accountabilities/domains of a proposal part. Use to review before managing individually.

Get all parts (proposed changes) of a tension. Review before submitting.

Get detailed tension status with per-user voting responses and timestamps.

Get details of a specific user including profile, roles, and contact info. Use it to resolve a user id to a name and email; when presenting users to a person, show names and/or emails, never bare ids.

Get details of a specific workspace including its purpose and member count

List a workspace's apps/features. Returns the FULL catalogue, each entry `{ _id, title, enabled }` — a disabled app is present with `enabled: false`, never absent, so test `enabled` and not presence. Note the field is `_id`, not `id`. Check before using features that require specific apps (e.g., Insights, Scrum, Meetings).

Nestr documentation, three modes. (1) Internal topic: `topic` with a curated key (search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, scrum, okr, ...); 'topics' lists them all. (2) Help article: `topic` with a slug from nestr.io/help/articles/<slug>; returns markdown plus a numbered list of its images. Images are never attached by default: includeImages:true takes the first maxImages screenshots, imageIndexes:[..] takes chosen ones. Attach when the user wants to see how something looks. (3) Search: `search` with free tex…

Count hints across a whole circle or workspace in one call. A hint on a single nest says "this one has this problem"; this says how many have it, which is the question you actually ask of a circle. Answers "how healthy is this circle", "how many projects are waiting with no reason", "how many roles have nobody in them" without reading every nest. Each result carries type, severity, count and a small sample to open. Read `notComputed`: it names every hint type this cannot count in one query, so a type listed there is unknown rather than zero. Do not sum counts across types, one nest can carry s…

List all circles (teams/departments) in a workspace. Response includes meta.total showing total matching count.

List who has access to what in this workspace: each binding's connector, its owner (a role's domain, a person, an agent, or the whole workspace), and who holds a credential on it. Shows when an agent is using a person's account, and never returns a secret. Use it to check whether access already exists before giving more, and to find the connectionId for nestr_get_connect_link. A row with pendingInstructionApprovals is held back on scheduled runs until a person in its audience approves the role's latest instructions; its instructionApprovalNote says who can release it and how.

The connector templates this deployment can add in one click, filtered to the ones it can actually offer. Each carries the vendor's real endpoint, transport, auth strategy and the deployment's OAuth client. CALL THIS FIRST, before nestr_register_connector, whenever the tool is a known vendor (Xero, HubSpot, Slack, Stripe, GitHub, Notion, Linear and so on). Hand-registering means guessing an endpoint, and a wrong guess authorises cleanly and then fails every call: a Xero connector registered against api.xero.com instead of the template's mcp.xero.com looked healthy in every record and returned…

List the workspace's connector catalog: the mcp / cli / api templates an admin has registered. Each entry holds no secret and shows its type, name, authStrategy, config, capabilities, exposure ({ userAgent, domainGated }) and whether it is enabled. Typical flow: register a connector, then bind it to a role's domain with nestr_bind_connector, then a human or agent connects the account via the credentials field's Connect button (the secret is captured out-of-band, never by the agent). Auth: any valid token can list.

List your open direct-message threads, most recently posted first. Closed ones are left out unless includeCompleted is set. Pass withUser to see only the ones with a particular person; withUser:'nestr_support' is your Nestradamus conversation. Each thread carries participants, so a flat list still tells you who you are talking to.

List items in the user's personal inbox. Spans all workspaces. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.

List available labels in a workspace. Each row carries only `_id` and `title`: for a label's fields, its `display` settings and autoComplete call nestr_get_label. Response includes meta.total showing total matching count. The list does not carry autoComplete, so it mixes labels a person can pick with internal machinery they cannot. Call nestr_get_label before offering a label as a choice to somebody.

List tensions created by or assigned to the current user. Check at session start and natural breakpoints. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

List notifications. Use type 'me' for direct (mentions, replies) or 'relevant' for organizational changes. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

List the occurrences of a recurring task, project or meeting, so you can name the one you want to act on. This is the ONLY way to see them: occurrences beyond the next one are virtual, meaning the rule produces the instant and no nest exists for it, so nestr_search and nestr_get_nest_children find nothing and asking them is not evidence the occurrences are missing. Returns one page mixing both kinds in date order, each entry carrying `instant` (epoch milliseconds, the key that identifies one occurrence), `virtual` (false means a real nest exists and `nestId` names it), `excluded` (this instant…

List the current user's personal labels (not workspace labels). Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

List threads in a support queue, most recently posted first. If you subscribe to the queue you get every thread in it; otherwise you get only the ones you raised, which is how you find your own open support tickets. Pass unread:true for just what has moved. Read one with nestr_get_dm_thread using the id you get back.

List the support queues you can see: the ones you monitor, plus any you have raised a thread in. Each carries `subscribed`, which decides what nestr_list_queue_threads returns for you.

List ALL roles that exist in a workspace, whoever fills them. Not the caller's roles: check each role's `users` array for who fills it, or use nestr_list_user_roles to ask who fills what. Response includes meta.total showing total matching count.

List tensions for a circle or role. Supports search filtering. Rows leave out text tab bodies (`fields` keys ending in `_texttab`); read those with nestr_get_nest.

List tensions awaiting the current user's consent vote. Check proactively. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Which roles does a person actually FILL? Omit userId for yourself. This is the only correct way to answer "what are my roles?" — nestr_list_roles returns every role in the workspace, most of which are somebody else's. An empty result means they fill no roles yet, which is normal for a new member: report that plainly and never substitute the workspace's role list.

List members of a workspace: its people, its agents, or both. Response includes meta.total showing total matching count. Also the tool to resolve user ids in bulk: when presenting users to a person, show names and/or emails, never bare ids. With agents:'only' this is how you find out which other agents exist and what each is for: an agent carries bot:true, its purpose in profile.agentDescription, and assistant:true when it may never fill a role. An assistant is the one to hand work to that needs a person's OWN credentials, which a role-filling agent cannot reach.

List workspaces. Prefer nestr_get_me with fullWorkspaces:true at session start. Paginated with meta.total.

Mark all unread in-app notifications as read for the current user. Returns { status, data: { markedCount } }. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Mark a conversation read up to and including this post. Works for any post, not only direct messages. The marker never moves backwards, so calling it on an older post is harmless.

Description is built at runtime.

The caller's own activity across ALL their workspaces, newest first (gated by workspace membership and the token's scope). Not scoped to a project or a single nest — it's everything you've done. For an agent, this is how it sees what it has done: past considerations (with the tools used and the outcome), comments, governance changes, and other actions. Agent internal considerations from direct-message runs are redacted to an anonymous marker unless you pass withUser with that conversation's counterpart. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure cal…

Post a message into a direct-message thread.

Read a single file attachment on a nest (or comment). Branches on contentType: JPEG, PNG, GIF and WebP return as viewable image content so you can see them (very large images return metadata only); JSON, XML and text (application/json, text/*, and SVG, which is markup) return as decoded UTF-8 text (large text is truncated); PDFs, other image formats and everything else return their metadata only (cannot be inlined). Get file ids from nestr_get_nest_files, or, for an image pasted into a nest's text, from the  reference in its content — those are not l…

Register a connector in the workspace catalog. PREFER A TEMPLATE: call nestr_list_connector_templates first and pass its id as templateId, which fills in the vendor's real endpoint, transport, auth strategy and this deployment's OAuth client. Hand-registering a known vendor means guessing an endpoint, and a wrong guess authorises cleanly and then fails every call. Only describe the transport yourself for something the deployment has no template for. A reusable mcp / cli / api template that holds no secret. Workspace-admin only. A non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagno…

Take a connector off an owner: the binding is removed and every credential on it revoked. Workspace-admin only. A domain left holding nothing goes back to being an ordinary descriptive domain.

Remove a connector from the workspace catalog. Workspace-admin only. Bindings that named it stop resolving, so prefer nestr_update_connector with enabled:false when you only want to pause it.

Remove one or more items from the daily plan by removing the 'now' label. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Remove the graph link from nestId to targetId. A link running the other way is left alone, and the error names the call that removes it. For example, remove a tension from a meeting's agenda by removing the 'meeting' relation.

Description is built at runtime.

Remove a proposal part, or propose deletion of an existing governance item.

Reorder inbox items. Provide a subset of IDs — they go to the top in given order, rest unchanged. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Reorder a single inbox item by positioning it before or after another inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Reorder a nest by positioning it before or after another nest.

Revoke the calling user's credential on a binding. The binding stays, so access can be restored by connecting again. Use nestr_remove_connection to remove the access entirely.

Run an agent now on a nest, optionally saying what the run is for. This is how one agent asks another to do something. The run is pinned to the nest you name and reports back there. You need assign rights on that nest and the agent must fill or be assigned to it, so this cannot run an agent anywhere in the workspace.

Search nests in a workspace. Supports operators like label:, assignee:, createdby:, completed:, in:, sort:. createdby: accepts me, an email address, or a user id. Always use completed:false for active work. See nestr_help('search') for full syntax. Results carry user ids; when presenting to a person, show names and/or emails. Pass `linkedUsers: true` to get them all resolved in the same request rather than calling nestr_get_user per id. Rows leave out text tab bodies (`fields` keys ending in `_texttab`); read those with nestr_get_nest.

Set how one agent operates on one nest: reactive, or autonomous on a cadence. The cadence (`recheck`) is "continuous" or an RRULE. Put the time of day in `start` and the zone in `tzid`, never in BYHOUR: weekdays at 09:00 Amsterdam time is recheck FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR with start 2026-10-12T09:00:00+02:00 and tzid Europe/Amsterdam. Applies to this nest and to the items under it that set nothing of their own; mode null clears this nest's own setting. A cadence re-checks one item until it is done, so it fits keeping an open-ended role or project moving. For a job that should happen aga…

Set or remove a task/project/meeting's recurrence rule. Pass an RFC-5545 RRULE string (e.g. 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=10') to set it, or rrule: null to remove it. Setting a rule creates NO nests: occurrences are computed from the rule and stay virtual until something touches one (completing it, moving its dates, opening it), at which point that occurrence alone becomes a real nest. Do not tell the user their occurrences have been created. The rule expands from the nest's start, or its due when it has no start, and is refused when it has neither, so set a date first. An invalid RRULE is…

Skip ONE occurrence of a recurring series, or with scope 'following' delete it and every later one. With scope 'occurrence' (the default) it is for the person away that week, the meeting cancelled once, the task that does not apply this time. It excludes that single instant and nothing else. It does NOT end the series (unless the occurrence skipped is the first and nothing follows it, see below), does not change the rule, does not move any other occurrence, and does not destroy history: every past occurrence stays exactly as it was, and the skipped instant stays visible in nestr_list_occurrenc…

Start a new direct-message thread with someone. Use it for a new subject rather than reopening an old thread. You must share a workspace with them, or already have a conversation with them. A DM needs at least one PERSON in it: agents cannot hold a private conversation with each other, and the server refuses one. That is the wrong channel rather than a missing permission, so do not ask anyone to widen anything. To reach another agent, comment on the work itself and mention them there, or raise a tension to the role that owns it, which keeps the exchange where the people accountable for the wor…

Change an existing agent's settings: its name, its description, whether it may search the web, its status, whether it may be assigned to roles, and its runtime config. Send only the fields to change; the rest are left as they are. Workspace-admin only; a non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). The description is what the agent is LIKE, shown as its purpose wherever it is listed. It is not the agent's instructions: what the agent should DO lives in a skill nest under the role it fills, so a stale description is fixed here and a stale instruction i…

Description is built at runtime.

Update a connector in the workspace catalog, or switch it on and off with `enabled`. Workspace-admin only. Switching it off, or narrowing its exposure, takes effect immediately everywhere it is used: the policy is re-read every time a credential is handed out, not only when access was given.

Update a direct-message thread: rename it, close or reopen it, or change who is in it. Send only the keys you want changed, as with nestr_update_nest. completed:true closes a conversation once it is dealt with, which takes it out of nestr_list_dms without losing it; completed:null reopens. `users` is the participant list you want, so read the thread first and send the list with someone added or removed; the bot and the person who raised the thread cannot be removed. Answers with the updated thread.

Description is built at runtime.

Description is built at runtime.

Edit ONE occurrence of a recurring series: move this week's meeting, retitle one instance, assign one occurrence to someone else. Takes the same edit fields as nestr_update_nest, but not accountabilities, domains or workspaceId. If the occurrence is still virtual it is materialized first, then the changes are applied to that occurrence only; the rule and every other occurrence are untouched. With no fields it only materializes the occurrence. Answers with the nest: use its `_id` with every other nest tool from then on. Not all-or-nothing: the occurrence is materialized before the changes are a…

Description is built at runtime.

Description is built at runtime.

Submit a tension for consent ('proposed') or retract it to 'draft'. Proposing asks every other member of the circle to consent and notifies them. When there is nobody else to ask, the server enacts the tension at once and answers `status: "enacted"`: a governance proposal in a single-member circle, or a work request with no output or whose requester is its only assignee. Otherwise resolution happens through those consent votes, in a governance meeting or in the Nestr app, not through this tool. To observe the outcome, read nestr_get_tension_status, which reports `accepted` once the tension is …

Upload a file and attach it to a nest (or comment; files are keyed by nestId, so a comment ID attaches the file to that comment). Provide the file one of two ways: content (UTF-8 text, for text-native files you author directly such as .md, .csv, .json, .html, .svg, or code) or dataBase64 (base64-encoded bytes you already have). Any content type is accepted; the upload is rejected if it exceeds the server's maximum size (default 10MB). Returns the new file's descriptor (id, name, contentType, size). Auth: a token with write access to the nest.

Another user's activity across the workspaces you share with them, newest first. Lets an agent see what a colleague or another agent has done: their past considerations (with the tools used and the outcome), comments, governance changes, and other actions. Agent internal considerations from direct-message runs show their substance only when you are a participant of that conversation, otherwise an anonymous marker. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.

The workspace's reference documents: an organisation constitution, a staff handbook, an onboarding guide, whatever this workspace uploaded for its agents to draw on. CALL THIS WITH NO ARGUMENTS FIRST to see what exists — the index lists each document with a description of what it holds and when to read it, and costs almost nothing. Then `search` across them for the passage that answers a question, or `fileId` to read one document. Prefer `search` over reading a whole document: the large ones run past half a million characters, and the answer is usually one section. These are the organisation's…