mcp MCP — MCP Radar

nestr_add_comment

Add a comment to a nest, for progress updates and discussion. Mentions need literal curly braces, see `body`. Optionally attach labels at creation.

Input schema

{'type': 'object', 'required': ['nestId', 'body'], 'properties': {'body': {'type': 'string', 'description': "Comment text. Supports HTML and @mentions. Mentions MUST use literal curly braces: `@{userId:roleId}`, NOT `@userId`. Without braces nothing is linked and nobody is notified. Forms: `@{userId:roleId}` (preferred, names the role), `@{userId}`, `@{email}`, `@{circle}` (all fillers in the nearest ancestor circle). The second id MUST be a ROLE or CIRCLE nest, never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. When you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on."}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Optional label IDs to attach at creation (e.g. 'decision', 'question', or a custom ID). Personal labels are auto-scoped to the caller. Discover IDs via nestr_list_labels / nestr_list_personal_labels."}, 'nestId': {'type': 'string', 'description': 'Nest or conversation the comment belongs to. A comment ID instead replies inside that thread. Direct-message conversations are flat, so a message ID there lands on the conversation and the response says where.'}}}

nestr_add_graph_link

Create a bidirectional graph link between two nests. E.g., link a tension to a meeting as an agenda item.

Input schema

{'type': 'object', 'required': ['nestId', 'relation', 'targetId'], 'properties': {'nestId': {'type': 'string', 'description': 'Source nest ID'}, 'relation': {'type': 'string', 'description': "Relation name (e.g., 'meeting' to link a tension to a meeting)"}, 'targetId': {'type': 'string', 'description': 'Target nest ID to link to'}}}

nestr_add_label

Add a label to a nest. Personal labels (like 'now') are automatically scoped to the authenticated user by the API. Will reject any attempt to add a prime label (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback) to a nest that already has one — a nest can only have one core identity.

Input schema

{'type': 'object', 'required': ['nestId', 'labelId'], 'properties': {'nestId': {'type': 'string', 'description': 'Nest ID'}, 'labelId': {'type': 'string', 'description': "Label ID to add (e.g., 'project', 'now', or a custom label ID)"}}}

nestr_add_tension_part

Add a part to a tension. A part is either the operational work the tension asks for or a governance change it proposes. Modes: OPERATIONAL OUTPUT (title, description, users, role, and no governance label) is what a work request is made of, and is the common case; new governance item (omit _id, give title plus a governance label such as ['role'] or ['policy']); change one (_id plus the changed fields; editing a role copies its accountabilities/domains in, so it reads as a full role edit); delete one (_id plus removeNest:true); election (roleId plus users:[userId], optional due, which assigns or reconfirms the filler and leaves accountabilities/domains untouched). The part you get back has its own _id and a sourceId, the output nest underneath it; nestr_modify_tension_part takes the part _id, not the sourceId. See nestr_help('tension-processing').

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'_id': {'type': 'string', 'description': 'ID of an existing governance item to change or remove. Omit to propose a new item.'}, 'due': {'type': 'string', 'description': 'Due or re-election date, ISO. For an election, the term end; omit for no term.'}, 'role': {'type': 'string', 'description': 'The role this output belongs to, for an operational output (pathway 3/4). Pair with users: users is WHO does it, role is the role it is asked of, and the work request names both ("Ada as Systems: ..."). A role id, not a title. Distinct from roleId, which is election mode.'}, 'title': {'type': 'string', 'description': 'Title for the governance item'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': 'User IDs to assign. For an election (with roleId), the one user being elected.'}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Item type, e.g. ['role'], ['circle'], ['policy'], ['accountability'], ['domain']"}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'roleId': {'type': 'string', 'description': 'ELECTION mode: the electable role to fill (Facilitator, Secretary, Rep Link or any electable role). Pair with users:[oneUserId] and optional due. Never with _id.'}, 'domains': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Domain titles on a role (replaces all; children tools for individual edits)'}, 'purpose': {'type': 'string', 'description': 'Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.'}, 'parentId': {'type': 'string', 'description': 'Parent ID — use to move/restructure items (e.g., move role to different circle)'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}, 'removeNest': {'type': 'boolean', 'description': 'With _id, propose deleting that governance item; it goes when the proposal is accepted. Not nestr_remove_tension_part, which undoes a part you already added.'}, 'description': {'type': 'string', 'description': 'The primary content field — detailed information about the item. Supports Markdown and HTML.'}, 'accountabilities': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Accountability titles on a role (replaces all; children tools for individual edits)'}}}

nestr_add_to_daily_plan

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

Input schema

{'type': 'object', 'required': ['nestIds'], 'properties': {'nestIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Array of nest IDs to add to the daily plan'}}}

nestr_add_workspace_user

Adds a user to a workspace by email, creating the account if needed. It SENDS A REAL INVITE EMAIL, so confirm with the requester first. Covers seats, membership, plan headcount, adding a colleague. It provisions only domains the workspace added and Nestr verified: personal providers (gmail.com) are always refused, and an added domain stays refused until verified. That limits this tool, not the workspace. The in-app invite (Workspace settings, Users, "Invite users") accepts any address with no domain check, so offer it first on a refusal. NEVER suggest clearing the workspace domain list: it keeps the requirement, kills the only way to meet it, and breaks auto-join. Suggest adding a domain only when they control that company domain. Nestr review takes up to 24 hours.

Input schema

{'type': 'object', 'required': ['workspaceId', 'username'], 'properties': {'fullName': {'type': 'string', 'description': 'Full name (for new accounts)'}, 'language': {'type': 'string', 'description': "Language preference (e.g., 'en', 'nl')"}, 'username': {'type': 'string', 'description': 'Email address of the user to add'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_api_spec

The deployment's own OpenAPI document, so you can check whether the API has something rather than concluding "I did not find it" and guessing. Call with no arguments for the operation index (method, path, one-line summary). `search` filters by keyword against path and summary. `path` returns the full schema for one operation, including its parameters. Use this to answer "is there an endpoint for X" with certainty, and note that a negative here is a real negative: if it is not in the spec, this deployment does not serve it. For the search query language rather than the HTTP surface, use nestr_help('search'); for a filter you are unsure of, `strict: true` on nestr_search tells you whether it applied.

Read only

Input schema

{'type': 'object', 'properties': {'path': {'type': 'string', 'description': "Return the full schema for one path, e.g. '/nests/{id}/children'."}, 'search': {'type': 'string', 'description': "Filter operations by keyword against path and summary, e.g. 'meeting', 'tension', 'duration'."}}}

nestr_bind_connector

Bind a registered connector to an owner so that owner can use it. Owner types: 'role' (ownerId is the role nest ID — the server finds or creates the connector's domain under it), 'role-domain' (ownerId is an existing domain nest ID), 'workspace' (ownerId is the workspace ID), 'user' (ownerId is a person's user ID, for their own account), or 'agent' (ownerId is a bot's user ID, for its own). A 'role' or 'role-domain' owner materialises a credentials field on the domain nest, so the role can use the connector and the Connect button renders there; the response then carries domainId (and domainCreated when the bind created it). After binding, a human or agent connects the account via that Connect button. The secret is captured out-of-band and is never seen by the agent. Workspace-admin only: a non-admin caller gets AUTH_SCOPE_INSUFFICIENT. The connector must already be registered (nestr_register_connector) and enabled. BIND TO THE ROLE, not to whoever fills it. A role binding is the governance act: the access belongs to the work, survives the filler changing, and is visible to the circle. Reach for 'role' by default — it is the usual onboarding path: pass the role nest ID and the server does the domain lookup. Use 'role-domain' only when you already have the domain nest ID and want to target it directly. 'user' is for what is genuinely one person's: their own mailbox, their own drive. Binding that to a role would hand it to whoever fills the role next, which is the opposite of what they asked for, so this is the one case where a role binding is wrong. It needs a workspace admin and the connector has to be open to user owners in the catalog; if either is missing, say which and what the admin has to do rather than falling back to a role binding. The work on a personal connection is then done by an agent that fills NO role, because filling a role and assisting are exclusive and only an assistant can act with a person's own access. 'agent' is the same shape for a bot's own account, used where a provider gives the agent its own login rather than borrowing a person's. It is the rarest of the four: prefer 'role', so the access belongs to the work and survives the filler changing. Both personal types are workspace-admin only and both need the connector open to user/agent owners, so a caller who is not an admin gets AUTH_SCOPE_INSUFFICIENT and should say which of the two is missing rather than binding to a role instead. Be careful arranging one agent's credential from another agent's run: it is a decision about what that agent may reach, so name what you are about to do and why before doing it.

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectorId', 'ownerType', 'ownerId'], 'properties': {'ownerId': {'type': 'string', 'description': "Owner ID. role: the role nest ID. role-domain: the domain nest ID. workspace: the workspace ID. user: the person's user ID. agent: the bot's user ID."}, 'ownerType': {'enum': ['role', 'workspace', 'role-domain', 'user', 'agent'], 'type': 'string', 'description': "Owner type. 'role' is the usual path: pass the role nest ID and the server finds or creates the connector's domain under it. 'role-domain' targets an existing domain directly. 'workspace' gives everyone. 'user' is one person's own account and 'agent' is one bot's own: both are personal, both are workspace-admin only, and both are wrong unless the thing really belongs to that single principal."}, 'connectorId': {'type': 'string', 'description': 'ID of an enabled connector from nestr_list_connectors'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID the connector and owner belong to'}}}

nestr_bulk_reorder

Bulk reorder nests. Provide a subset of IDs — they go to the top in given order, rest unchanged.

Input schema

{'type': 'object', 'required': ['workspaceId', 'nestIds'], 'properties': {'nestIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Array of nest IDs in the desired order'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_create_agent

Create an agent user in the workspace. Workspace-admin only; a non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). What decides how an agent behaves at run time is not this flag: it is whether the agent FILLS ANY ROLE in the workspace at that moment. Filling one and assisting are exclusive, and the test is not 'does it fill THIS role' but 'does it fill any', so one role anywhere makes every one of its runs a role-filler run, acting with that role's authority and reaching only the role's connectors. An agent that fills none assists whoever engages it, acting with THAT person's authority and reaching what they reach, their own connectors included. roleAssignable decides whether that can ever change. Default (true) is an ordinary agent: it assists while it holds no role, and becomes a filler the moment anyone assigns it to one. Pass false for an ASSISTANT: it can never be assigned to a role, so it can never stop being able to act for a person. Prefer false whenever the agent exists to help people with work that follows them, because otherwise a single well-meant role assignment silently ends that. Either way, work that follows a PERSON (their mailbox, their drive, their queue) puts the agent on the TASK beside them and never in the role's users. Assigning it to the role is the specific mistake: it then cannot reach anything of theirs, reports that it holds no external tool sources, and suggests binding their account to the role, which would hand it to whoever fills that role next. An agent and the role it fills are two different things, named differently: the agent carries its own name (Collab), the role is named for the WORK (Marketing). Do not name the role after the agent. Keeping them apart is what lets the agent be replaced without the role losing its purpose, accountabilities and history, and lets one agent fill several roles. The agent's instructions do not go here: they belong in a skill nest under the role, which loads whenever the role acts. agentConfig is runtime wiring only.

Input schema

{'type': 'object', 'required': ['workspaceId', 'name'], 'properties': {'name': {'type': 'string', 'description': "The AGENT's own name, as its identity calls it (e.g. 'Collab'). Not the name of the work: that belongs to the role this agent will fill."}, 'agentConfig': {'type': 'object', 'description': "Runtime wiring, not persona: { runtimeCallbackUrl (https, or http to a *.svc.cluster.local service), tokenTtlSeconds (30-1800) }. Omit for an agent that runs on Nestr's own runtime."}, 'description': {'type': 'string', 'description': 'What the agent is LIKE: its character and what it is careful about. Not its instructions, which belong in a skill on the role.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID to create the agent in'}, 'roleAssignable': {'type': 'boolean', 'description': 'Defaults to true, meaning it MAY be assigned to a role. It still assists while it holds none; assigning it to one is what ends that. Pass false for an ASSISTANT, which can never be assigned and so can never stop acting for a person. See the tool description.'}}}

nestr_create_inbox_item

Quick capture: add an item to the inbox for later processing. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Input schema

{'type': 'object', 'required': ['title'], 'properties': {'title': {'type': 'string', 'description': 'Title of the inbox item (plain text, HTML stripped)'}, 'description': {'type': 'string', 'description': 'Additional details or context (supports Markdown and HTML)'}}}

nestr_create_nest

Create a nest under a parent. Labels define the type, e.g. ['project'], ['role']. At most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone): they are the nest's identity and cannot coexist. Only exception: userstory may pair with project. Sprint/epic/milestone never pair; stories link to those via graph relations. In established workspaces prefer the tension flow for governance. Meetings attach to a circle that ALREADY exists — the workspace anchor circle counts, and is the right parent when no sub-circle fits. Never create a circle to hold a meeting. Use `['meeting','circle-meeting']` for a tactical meeting, `['meeting','governance']` for a governance meeting, and set `due` to the start time. See nestr_help('labels') and nestr_help('meetings').

Input schema

{'type': 'object', 'required': ['parentId', 'title'], 'properties': {'due': {'type': 'string', 'description': 'Due date (ISO 8601). SET THIS whenever the item is meant to happen at a time. It is a field, not a title: the sweep that fires dated work reads `due` and nothing else, so a task called "Daily digest, 28 Aug" with no due is invisible to it and simply never runs, with nothing anywhere saying so. For projects/tasks: deadline. For meetings: start time.'}, 'title': {'type': 'string', 'description': 'Title of the new nest (plain text, HTML tags stripped)'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': "User IDs to assign. ALWAYS set this for projects and tasks — use the role filler's user ID. Placing a nest under a role does NOT auto-assign it."}, 'fields': {'type': 'object', 'description': "Structured field values to set on creation (e.g., { 'project.status': 'Current' }, { 'skill.type': 'process' }). Same shape as nestr_update_nest fields — saves a follow-up update call."}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Label IDs to apply (e.g., 'project', 'role', 'circle')"}, 'domains': {'type': 'array', 'items': {'type': 'string'}, 'description': "Domain titles for roles/circles. Each becomes a domain child nest. Only used when labels include 'role' or 'circle'. Requires workspaceId."}, 'purpose': {'type': 'string', 'description': 'Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.'}, 'parentId': {'type': 'string', 'description': 'Parent nest ID (workspace, circle, or project)'}, 'description': {'type': 'string', 'description': 'The primary content field: details, context, acceptance criteria. Structured data goes in fields, progress in comments. Supports Markdown and HTML.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID. Required when creating roles/circles with accountabilities or domains.'}, 'accountabilities': {'type': 'array', 'items': {'type': 'string'}, 'description': "Accountability titles for roles/circles. Each becomes an accountability child nest. Only used when labels include 'role' or 'circle'. Requires workspaceId."}}}

nestr_create_personal_label

Create a personal label. Can be used across workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Input schema

{'type': 'object', 'required': ['title'], 'properties': {'icon': {'type': 'string', 'description': 'Label icon identifier'}, 'color': {'type': 'string', 'description': "Label color (hex code, e.g., '#FF5733')"}, 'title': {'type': 'string', 'description': 'Label title'}, 'description': {'type': 'string', 'description': 'Label description'}}}

nestr_create_tension

Create a tension on a role or circle. Tensions drive organizational change. See nestr_help('tension-processing') for guidance on placement and pathways.

Input schema

{'type': 'object', 'required': ['nestId', 'title'], 'properties': {'needs': {'type': 'string', 'description': 'The need that is alive — what personal or organizational need is not being met (plain text)'}, 'title': {'type': 'string', 'description': 'The gap — what is the difference between current reality and desired state (plain text)'}, 'nestId': {'type': 'string', 'description': 'ID of the role or circle to create the tension on. Place on a role to indicate that role is sensing the tension. Place on a circle for cross-role or governance tensions (use individual-action label if sensed personally without role authority).'}, 'feeling': {'type': 'string', 'description': 'The feeling this tension evokes — separated to keep the organizational response clean (plain text)'}, 'description': {'type': 'string', 'description': 'The observable facts — what you see/hear/experience (supports Markdown and HTML)'}}}

nestr_create_tension_part_child

Add a new accountability or domain to a proposal part. When the proposal is enacted, this creates a new accountability/domain on the role.

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId', 'title', 'labels'], 'properties': {'title': {'type': 'string', 'description': 'Title for the new accountability or domain'}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Labels defining the type: ['accountability'] or ['domain']"}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_create_workspace

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.

Input schema

{'type': 'object', 'required': ['title'], 'properties': {'apps': {'type': 'array', 'items': {'enum': ['okr', 'feedback', 'insights'], 'type': 'string'}, 'description': "Apps to enable (e.g., ['okr', 'feedback']). 'insights' requires pro plan."}, 'plan': {'enum': ['starter', 'pro'], 'type': 'string', 'description': "Subscription plan for collaborative workspaces. Defaults to 'pro' (17-day trial)."}, 'type': {'enum': ['personal', 'collaborative'], 'type': 'string', 'description': "'personal' for individual use (free forever), 'collaborative' for team use (free trial). Defaults to 'collaborative'."}, 'title': {'type': 'string', 'description': 'Workspace name'}, 'layout': {'enum': ['board', 'list'], 'type': 'string', 'description': "Layout style for personal workspaces. 'board' creates kanban columns (Todo, Doing, Done)."}, 'purpose': {'type': 'string', 'description': 'Aspirational future state of the organization — a short north-star statement, not project details'}, 'governance': {'enum': ['holacracy', 'sociocracy', 'roles_circles'], 'type': 'string', 'description': "Self-organization model. Defaults to 'roles_circles' (generic role-based)."}}}

nestr_delete_comment

Delete a comment (soft delete).

Destructive

Input schema

{'type': 'object', 'required': ['commentId'], 'properties': {'commentId': {'type': 'string', 'description': 'Comment ID to delete'}}}

nestr_delete_file

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.

Destructive

Input schema

{'type': 'object', 'required': ['nestId', 'fileId'], 'properties': {'fileId': {'type': 'string', 'description': 'File ID from nestr_get_nest_files'}, 'nestId': {'type': 'string', 'description': 'Nest or comment ID the file is attached to'}}}

nestr_delete_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 agent token, so a caller who could not delete the nest themselves is refused with 403.

Destructive

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'Nest ID to delete'}}}

nestr_delete_series

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. Refused when the nest has no recurrence.

Destructive

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'The series, or any occurrence of it.'}}}

nestr_delete_tension

Delete a tension (soft delete).

Destructive

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'tensionId': {'type': 'string', 'description': 'Tension ID to delete'}}}

nestr_delete_tension_part_child

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

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId', 'childId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID'}, 'childId': {'type': 'string', 'description': 'Child ID to soft-delete'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_diagnose

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.

Read only

Input schema

{'type': 'object', 'properties': {}}

nestr_escalate_to_support

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.

Input schema

{'type': 'object', 'required': ['threadId', 'reason'], 'properties': {'reason': {'type': 'string', 'description': 'One or two sentences for whoever picks this up: what is needed and what has been tried. They can read the thread, so do not summarise it.'}, 'threadId': {'type': 'string', 'description': 'Thread id to escalate'}}}

nestr_explain_nest

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'. For connection/auth errors use nestr_diagnose instead.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'The nest to diagnose (a single id).'}, 'whoCan': {'type': 'string', 'description': 'Comma-separated ops (read,update,delete,create) to also list who can perform each on this nest.'}, 'forUser': {'type': 'string', 'description': 'Diagnose rights for this user id instead of the caller. Requires the caller to be an admin of the nest.'}}}

nestr_get_agent_connectors

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'agentUserId'], 'properties': {'agentUserId': {'type': 'string', 'description': "The agent's bot user ID"}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID the agent belongs to'}}}

nestr_get_circle

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

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'circleId'], 'properties': {'circleId': {'type': 'string', 'description': 'Circle ID'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_circle_roles

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

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'circleId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'circleId': {'type': 'string', 'description': 'Circle ID'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_comments

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.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'depth': {'oneOf': [{'type': 'number'}, {'enum': ['all'], 'type': 'string'}], 'description': "How deep below the context nest to look for comments. 0 (default) returns only comments directly on this nest; N includes comments on descendants up to N levels deep; 'all' includes comments on this nest and every descendant."}, 'nestId': {'type': 'string', 'description': "Nest ID to get comments from. Pass a workspace ID to gather communication across the whole workspace (combine with depth='all')."}, 'unread': {'type': 'boolean', 'description': 'true for comments you have not read, false for the ones you have. Omit for all. Combine with depth to sweep a circle for what you have missed.'}}}

nestr_get_connect_link

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.

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectionId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID the binding belongs to'}, 'connectionId': {'type': 'string', 'description': 'Binding ID from nestr_list_connections'}}}

nestr_get_daily_plan

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 only

Input schema

{'type': 'object', 'properties': {'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_dm_posts

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.

Read only

Input schema

{'type': 'object', 'required': ['threadId'], 'properties': {'depth': {'type': ['number', 'string'], 'description': "Include posts on descendant nests, or 'all'"}, 'unread': {'type': 'boolean', 'description': 'true for unread posts, false for read ones. Omit for all.'}, 'threadId': {'type': 'string', 'description': 'Thread id'}}}

nestr_get_dm_thread

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.

Read only

Input schema

{'type': 'object', 'required': ['threadId'], 'properties': {'unread': {'type': 'boolean', 'description': 'true embeds unread posts, false embeds read ones'}, 'threadId': {'type': 'string', 'description': 'Thread id'}}}

nestr_get_graph_links

Get nests linked via a named graph relation. Use 'meeting' relation to get agenda items or linked meetings.

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'relation'], 'properties': {'page': {'type': 'number', 'description': 'Page number for pagination'}, 'limit': {'type': 'number', 'description': 'Max results per page (default 50)'}, 'nestId': {'type': 'string', 'description': 'Nest ID to get graph links for'}, 'relation': {'type': 'string', 'description': "Relation name (e.g., 'meeting' for meeting agenda items)"}, 'direction': {'enum': ['outgoing', 'incoming'], 'type': 'string', 'description': "Link direction: 'outgoing' (default) = links FROM this nest, 'incoming' = links TO this nest"}}}

nestr_get_inbox_item

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

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'Inbox item ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_insight

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'metricId'], 'properties': {'metricId': {'type': 'string', 'description': "Metric ID/type from getInsights (e.g., 'role_count', 'tactical_completed')"}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_get_insight_history

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

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'metricId'], 'properties': {'to': {'type': 'string', 'description': 'End date (ISO format)'}, 'from': {'type': 'string', 'description': 'Start date (ISO format)'}, 'limit': {'type': 'number', 'description': 'Maximum data points'}, 'metricId': {'type': 'string', 'description': 'Metric ID from getInsights'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_get_insights

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').

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'nestId': {'type': 'string', 'description': 'Filter metrics for a specific circle/nest (Pro plan only). Cannot be combined with userId.'}, 'userId': {'type': 'string', 'description': 'Filter metrics for a specific user (Pro plan only). Cannot be combined with nestId.'}, 'endDate': {'type': 'string', 'description': 'End date for metrics query (ISO format)'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'includeSubCircles': {'type': 'boolean', 'description': 'Include metrics from sub-circles (default: true). Cannot be false when userId is provided.'}}}

nestr_get_label

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 carrying it, so offer those two routes rather than saying it cannot be done. Every check tests for an explicit false, so a label that omits the property is shown normally: treat missing as visible, not as unknown. Only this single-label read returns autoComplete; nestr_list_labels does not.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'labelId'], 'properties': {'labelId': {'type': 'string', 'description': 'Label ID'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_get_me

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

Read only

Input schema

{'type': 'object', 'properties': {'fullWorkspaces': {'type': 'boolean', 'description': 'Set true to include full workspace details. Recommended on first call.'}}}

nestr_get_nest

Get nest details. Supports comma-separated IDs for batch fetch. Add hints=true for contextual signals, fieldsMetaData=true for field schemas. 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.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'hints': {'enum': ['summary', 'full', True, False], 'type': ['string', 'boolean'], 'description': "Contextual hints. 'summary' keeps the per-nest signal (type, severity, count, url, and the `query` that finds every other nest with the same problem) and drops the fixed teaching prose and endpoint list. 'full' is the whole payload. false for none. Defaults to 'full' on a single read, which is what you want when you asked about one nest."}, 'nestId': {'type': 'string', 'description': "Nest ID, or comma-separated IDs for a batch (e.g. 'id1,id2'). Keep the URL under 2000 chars."}, 'rights': {'type': 'boolean', 'description': "Single nest. The caller's composed rights (self read/update/delete) plus a deny trace naming what blocks each op, and why."}, 'whoCan': {'type': 'string', 'description': 'Single nest. Comma-separated ops (read,update,delete,create): who can perform each (admins + role-holders), with contact for admin callers.'}, 'forUser': {'type': 'string', 'description': 'Single nest, with rights=true. Rights for this user id instead of the caller. Caller must be a nest admin.'}, 'hintTypes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Keep only these hint types.'}, 'provenance': {'type': 'boolean', 'description': 'Single nest. Which label and circle context defines each field and property, e.g. why a role has a given icon.'}, 'minSeverity': {'enum': ['info', 'suggestion', 'warning', 'alert'], 'type': 'string', 'description': 'Drop hints below this severity.'}, 'fieldsMetaData': {'type': 'boolean', 'description': 'Set to true to include field schema metadata (available options, field types)'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_nest_children

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.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'hints': {'enum': ['summary', 'full', True, False], 'type': ['string', 'boolean'], 'description': "Contextual hints. 'summary' keeps the per-nest signal (type, severity, count, url, and the `query` that finds every other nest with the same problem) and drops the fixed teaching prose and endpoint list. 'full' is the whole payload. false for none. Defaults to 'summary' here: a listing at 'full' repeats the same paragraph once per row."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'nestId': {'type': 'string', 'description': 'Parent nest ID'}, 'search': {'type': 'string', 'description': "Search scoped to this nest, full operator syntax. Ask for the subset you want instead of fetching every child and filtering: `label:role` for a circle's roles, `label:project fields.project.status:Waiting` for its waiting projects. `depth:1` is applied when you set no depth and the response says so in `appliedDefaults`; pass `depth:2` or higher to reach further down."}, 'hintTypes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Keep only these hint types.'}, '_listTitle': {'type': 'string', 'description': 'Short descriptive title for the list UI header (e.g., "Tasks for Website Redesign", "API project sub-tasks"). Include the parent name for context.'}, 'linkedUsers': {'type': 'boolean', 'description': 'Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id.'}, 'minSeverity': {'enum': ['info', 'suggestion', 'warning', 'alert'], 'type': 'string', 'description': 'Drop hints below this severity.'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_nest_files

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 (images come back as viewable image content). Auth: any valid token with access to the nest.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'Nest or comment ID whose file attachments to list'}}}

nestr_get_projects

List all projects in a workspace. Check fields['project.status'] for status (Future/Current/Waiting/Done). Paginated.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, '_listTitle': {'type': 'string', 'description': 'Short descriptive title for the list UI header (e.g., "Engineering projects", "All projects"). Omit for default.'}, 'linkedUsers': {'type': 'boolean', 'description': 'Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_tension

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

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_get_tension_changes

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

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID to get changes for'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_get_tension_part_children

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

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_get_tension_parts

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

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_get_tension_status

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

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_get_user

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'userId'], 'properties': {'userId': {'type': 'string', 'description': 'User ID'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_get_workspace

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

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_get_workspace_apps

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).

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_help

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 text, **in English whatever language the conversation is in** — the corpus is English and the index scores slugs and keywords, so a query in another language usually returns nothing; returns ranked matches, each a title and one-line summary, tolerant of typos and synonyms (kanban/sprint to scrum). A topic is tried internally first, then as an article. Every response opens with 'Resolved as:' naming the mode, and topics and articles cross-link. Call before unfamiliar operations. No auth.

Read only

Input schema

{'type': 'object', 'properties': {'topic': {'type': 'string', 'description': "Internal topic key or help-article slug. Use 'topics' for the full list of internal topics."}, 'search': {'type': 'string', 'description': 'Free-text query against the public help articles. Returns slugs to fetch via `topic`.'}, 'maxImages': {'type': 'integer', 'minimum': 1, 'description': 'Article mode. Caps the default selection (first N content images). Default 3, max 6. Ignored when imageIndexes is set.'}, 'imageIndexes': {'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'description': 'Article mode. Attach screenshots by [index] from the numbered list in a prior response, e.g. [4,5,6]. Overrides the default selection and the maxImages cap, attaching exactly these in order.'}, 'includeImages': {'type': 'boolean', 'description': 'Article mode. Default false (markdown plus a numbered image-URL list). True attaches the first maxImages content screenshots inline, downscaled. Header, thumbnail and uncaptioned images are never auto-attached; reach those with imageIndexes.'}}}

nestr_hints_rollup

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 several; ask for a single hintTypes when you want a number that adds up.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'Nest to roll up. A circle or the workspace root is the useful scope.'}, 'hintTypes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Count only these hint types. Omit for every type this can compute.'}, 'sampleSize': {'type': 'number', 'description': 'Example nests per type. Default 10, max 100, 0 for counts only.'}, 'minSeverity': {'enum': ['info', 'suggestion', 'warning', 'alert'], 'type': 'string', 'description': 'Drop rules below this severity. \'warning\' is the useful floor for "what needs attention".'}}}

nestr_list_circles

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

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_list_connections

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID whose bindings to list'}, 'includeDisabled': {'type': 'boolean', 'description': 'Include removed bindings. Default false.'}}}

nestr_list_connectors

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID whose connector catalog to list'}}}

nestr_list_connector_templates

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 403 forever. Pass the id you find here as templateId to nestr_register_connector. Workspace-admin only.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID whose available connector templates to list'}}}

nestr_list_dms

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.

Read only

Input schema

{'type': 'object', 'properties': {'page': {'type': 'number', 'description': 'Page number, 1-based'}, 'limit': {'type': 'number', 'description': 'Threads per page (default 50, max 200)'}, 'unread': {'type': 'boolean', 'description': 'Only threads with messages you have not read'}, 'withUser': {'type': 'string', 'description': 'Only threads with this person: user id, username or email'}, 'includeCompleted': {'type': 'boolean', 'description': 'Also return closed conversations (left out by default)'}}}

nestr_list_inbox

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.

Read only

Input schema

{'type': 'object', 'properties': {'completedAfter': {'type': 'string', 'description': 'Include completed items from this date (ISO format). If omitted, only non-completed items are returned. For reordering, this default is usually sufficient — nestr_reorder_inbox only requires the IDs of items you want to reposition.'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_list_labels

List available labels in a workspace. 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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'search': {'type': 'string', 'description': 'Search query'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_list_my_tensions

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.

Read only

Input schema

{'type': 'object', 'properties': {'context': {'type': 'string', 'description': 'Optional context filter (e.g., workspace ID or circle ID)'}}}

nestr_list_notifications

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.

Read only

Input schema

{'type': 'object', 'properties': {'skip': {'type': 'number', 'description': 'Number of results to skip (default 0)'}, 'type': {'enum': ['all', 'me', 'relevant'], 'type': 'string', 'description': "Filter by type: 'all' (default), 'me' (direct), 'relevant' (delayed)"}, 'group': {'type': 'string', 'description': 'Filter by group (mentions, replies, direct_message, reactions, updates, governance)'}, 'limit': {'type': 'number', 'description': 'Max results (default 50, max 200)'}, 'showRead': {'type': 'boolean', 'description': 'Include already-read notifications (default false)'}}}

nestr_list_occurrences

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 is skipped by the series) and `completed`. Cursor-paged, not page-paged: a rule with no end produces occurrences forever, so there is no total. Pass `nextCursor` back as `cursor` while `hasMore` is true, and `direction: 'past'` to read history. What to do with an `instant`: skip that occurrence with nestr_skip_occurrence (scope 'following' deletes it and every later one), edit that one occurrence with nestr_update_occurrence, or delete the whole series with nestr_delete_series.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'limit': {'type': 'number', 'description': 'Occurrences per page. Default 10, capped at 50.'}, 'cursor': {'type': ['number', 'string'], 'description': 'Walk outward from this instant, exclusive. Pass back nextCursor from the previous page. Defaults to now.'}, 'nestId': {'type': 'string', 'description': 'The series, or any occurrence of it. Both resolve to the same series.'}, 'direction': {'enum': ['future', 'past'], 'type': 'string', 'description': "'future' (default) lists upcoming occurrences, soonest first. 'past' lists history, most recent first."}}}

nestr_list_personal_labels

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

Read only

Input schema

{'type': 'object', 'properties': {}}

nestr_list_queues

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.

Read only

Input schema

{'type': 'object', 'properties': {}}

nestr_list_queue_threads

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.

Read only

Input schema

{'type': 'object', 'required': ['key'], 'properties': {'key': {'type': 'string', 'description': "Queue key, e.g. 'support'"}, 'unread': {'type': 'boolean', 'description': 'Only threads you have not read'}}}

nestr_list_roles

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'linkedUsers': {'type': 'boolean', 'description': 'Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_list_tensions

List tensions for a circle or role. Supports search filtering.

Read only

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Max results to return'}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role to list tensions for'}, 'search': {'type': 'string', 'description': 'Search query to filter tensions'}}}

nestr_list_tensions_awaiting_consent

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

Read only

Input schema

{'type': 'object', 'properties': {'context': {'type': 'string', 'description': 'Optional context filter (e.g., workspace ID or circle ID)'}}}

nestr_list_user_roles

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.

Read only

Input schema

{'type': 'object', 'properties': {'userId': {'type': 'string', 'description': 'User ID to look up. Omit for yourself. Requires workspaceId when set.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID. Required when userId is set; omit to answer across every workspace you belong to.'}}}

nestr_list_users

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed)'}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'agents': {'enum': ['only', 'exclude'], 'type': 'string', 'description': "'only' for this workspace's agents, 'exclude' for its people. Omit for both."}, 'search': {'type': 'string', 'description': 'Search by name or email'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID'}}}

nestr_list_workspaces

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

Read only

Input schema

{'type': 'object', 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed) for pagination'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only)."}, 'limit': {'type': 'number', 'description': 'Omit on first call to see meta.total count'}, 'search': {'type': 'string', 'description': 'Search query to filter workspaces'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_mark_notifications_read

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.

Input schema

{'type': 'object', 'properties': {}}

nestr_mark_post_read

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.

Input schema

{'type': 'object', 'required': ['postId'], 'properties': {'postId': {'type': 'string', 'description': 'Post to mark read up to'}}}

nestr_modify_tension_part

Modify an existing proposal part. For individual accountability/domain changes, use the children tools.

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId'], 'properties': {'due': {'type': 'string', 'description': 'Updated due date (ISO format)'}, 'role': {'type': 'string', 'description': 'Updated role for an operational output. A role id; pass an empty string to clear it.'}, 'title': {'type': 'string', 'description': 'Updated title'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Updated user assignments'}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Updated labels'}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID to modify'}, 'domains': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Updated domains (replaces all; children tools for individual edits)'}, 'purpose': {'type': 'string', 'description': 'Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.'}, 'parentId': {'type': 'string', 'description': 'Updated parent ID'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}, 'description': {'type': 'string', 'description': 'Updated description — the primary content field. Supports Markdown and HTML.'}, 'accountabilities': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Updated accountabilities (replaces all; children tools for individual edits)'}}}

nestr_my_activity

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 call nestr_diagnose.

Read only

Input schema

{'type': 'object', 'properties': {'limit': {'type': 'number', 'description': 'Max activity items to return (default 50, max 200).'}, 'withUser': {'type': 'string', 'description': "Scope DM considerations to the conversation with this user id. Agent internal considerations from direct-message runs are redacted to an anonymous marker unless you name that conversation's counterpart here."}}}

nestr_post_dm_message

Post a message into a direct-message thread.

Input schema

{'type': 'object', 'required': ['threadId', 'body'], 'properties': {'body': {'type': 'string', 'description': 'Message text. Supports HTML and Markdown.'}, 'threadId': {'type': 'string', 'description': 'Thread id'}}}

nestr_read_file

Read a single file attachment on a nest (or comment). Branches on contentType: images (image/*) return as viewable image content so you can see them (very large images return metadata only); JSON and text (application/json, text/*) return as decoded UTF-8 text (large text is truncated); PDFs and other types return their metadata only (cannot be inlined yet). Get file ids from nestr_get_nest_files, or, for an image pasted into a nest's text, from the ![name](/file/download?id=FILE_ID&name=NAME) reference in its content — those are not listed by nestr_get_nest_files but are readable here. A comment ID works as the nestId. Auth: any valid token with access to the nest.

Read only

Input schema

{'type': 'object', 'required': ['nestId', 'fileId'], 'properties': {'fileId': {'type': 'string', 'description': 'File ID from nestr_get_nest_files'}, 'nestId': {'type': 'string', 'description': 'Nest or comment ID the file is attached to'}}}

nestr_register_connector

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_diagnose on any auth error). Provide type ('mcp' or 'api' need a url in config; 'cli' needs a command) and a unique name; optionally capabilities, exposure ({ userAgent, domainGated }), and authStrategy ('secret' or 'oauth2'). This only creates the template. Typical flow: register here, then bind it to a role's DOMAIN with nestr_bind_connector (create one under the role with nestr_create_nest and labels ['circleplus-domain'] if the role has none yet: the bind refuses a role id), then a human or agent connects the account via the credentials field's Connect button. The secret is captured out-of-band through that button, never by the agent.

Input schema

{'type': 'object', 'required': ['workspaceId'], 'properties': {'name': {'type': 'string', 'description': "Unique connector name within the workspace catalog. Required unless templateId is given, where it defaults to the template's own name."}, 'type': {'enum': ['mcp', 'cli', 'api'], 'type': 'string', 'description': "Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command). Required unless templateId is given."}, 'config': {'type': 'object', 'description': 'Transport config, no secret. mcp/api need a url, cli a command. Optional non-secret headers go under headers.'}, 'exposure': {'type': 'object', 'description': "Which owners may bind: { userAgent: boolean, domainGated: boolean }. domainGated:true allows binding to a role's domain."}, 'templateId': {'type': 'string', 'description': 'Id of a template from nestr_list_connector_templates. Given this, everything else is filled in from the template and you should omit type/config/capabilities/exposure/authStrategy. ALWAYS prefer this over hand-registering a vendor the deployment already knows.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID to register the connector in'}, 'authStrategy': {'enum': ['secret', 'oauth2'], 'type': 'string', 'description': "How a principal connects: 'secret' (one-time, via the Connect button) or 'oauth2'. The agent never sees it."}, 'capabilities': {'type': 'object', 'description': '{ discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime.'}}}

nestr_remove_connection

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.

Destructive

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectionId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID the binding belongs to'}, 'connectionId': {'type': 'string', 'description': 'Binding ID from nestr_list_connections'}}}

nestr_remove_connector

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.

Destructive

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectorId'], 'properties': {'connectorId': {'type': 'string', 'description': 'ID of the connector to remove'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID the connector belongs to'}}}

nestr_remove_from_daily_plan

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.

Input schema

{'type': 'object', 'required': ['nestIds'], 'properties': {'nestIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Array of nest IDs to remove from the daily plan'}}}

nestr_remove_graph_link

Remove a graph link between two nests. For example, remove a tension from a meeting's agenda by removing the 'meeting' relation.

Destructive

Input schema

{'type': 'object', 'required': ['nestId', 'relation', 'targetId'], 'properties': {'nestId': {'type': 'string', 'description': 'Source nest ID'}, 'relation': {'type': 'string', 'description': "Relation name (e.g., 'meeting')"}, 'targetId': {'type': 'string', 'description': 'Target nest ID to unlink'}}}

nestr_remove_label

Remove a label from a nest. Personal labels (like 'now') are automatically scoped to the authenticated user by the API.

Input schema

{'type': 'object', 'required': ['nestId', 'labelId'], 'properties': {'nestId': {'type': 'string', 'description': 'Nest ID'}, 'labelId': {'type': 'string', 'description': 'Label ID to remove'}}}

nestr_remove_tension_part

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

Destructive

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID to remove from the proposal'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_reorder_inbox

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.

Input schema

{'type': 'object', 'required': ['nestIds'], 'properties': {'nestIds': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Array of inbox item IDs in the desired order'}}}

nestr_reorder_inbox_item

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.

Input schema

{'type': 'object', 'required': ['nestId', 'position', 'relatedNestId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the inbox item to reorder'}, 'position': {'enum': ['before', 'after'], 'type': 'string', 'description': 'Position relative to the reference item'}, 'relatedNestId': {'type': 'string', 'description': 'ID of the reference inbox item to position relative to'}}}

nestr_reorder_nest

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

Input schema

{'type': 'object', 'required': ['nestId', 'position', 'relatedNestId'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the nest to reorder'}, 'position': {'enum': ['before', 'after'], 'type': 'string', 'description': 'Position relative to the reference nest'}, 'relatedNestId': {'type': 'string', 'description': 'ID of the reference nest to position relative to'}}}

nestr_revoke_connection_credential

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.

Destructive

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectionId'], 'properties': {'workspaceId': {'type': 'string', 'description': 'Workspace ID the binding belongs to'}, 'connectionId': {'type': 'string', 'description': 'Binding ID from nestr_list_connections'}}}

nestr_run_agent

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.

Input schema

{'type': 'object', 'required': ['workspaceId', 'agentUserId', 'nestId'], 'properties': {'nestId': {'type': 'string', 'description': 'The nest the run is pinned to: a role, a project, a task'}, 'message': {'type': 'string', 'description': "What this run is for. Omit for a plain 'advance this item' run."}, 'agentUserId': {'type': 'string', 'description': "The agent's bot user ID"}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID the agent belongs to'}}}

nestr_search

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.

Read only

Input schema

{'type': 'object', 'required': ['workspaceId', 'query'], 'properties': {'page': {'type': 'number', 'description': 'Page number (1-indexed) for fetching additional pages'}, 'sort': {'type': 'string', 'description': "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only). Takes precedence over sort:/sort-order: operators in the query."}, 'limit': {'type': 'number', 'description': 'Max results per page. Omit on the first call so meta.total shows the match count.'}, 'query': {'type': 'string', 'description': "Search query with optional operators (e.g., 'label:role', 'assignee:me completed:false')"}, 'strict': {'type': 'boolean', 'description': 'Reject the search when any operator, label or field filter in it was not recognised, rather than silently returning a broader result. Use it whenever you are counting rather than browsing: without it, a mistyped filter comes back as a real and larger answer with nothing to say the filter was dropped.'}, '_listTitle': {'type': 'string', 'description': 'Short title for the list UI header, 2-4 words, e.g. Marketing projects. Say what is shown, not the query.'}, 'linkedUsers': {'type': 'boolean', 'description': 'Resolve every user id in the results to a full user, returned once in `linked.users`. Prefer this over calling nestr_get_user per id.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID to search in'}, 'stripDescription': {'type': 'boolean', 'description': 'Strip description fields to shrink the response. Use for bulk or index reads.'}}}

nestr_set_recurrence

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 rejected before anything is written. Removing the rule stops future occurrences and keeps anything already materialized, detached from the series. Do not use this to leave out dates: bounding the series with a COUNT or UNTIL and creating a second recurring nest after the gap leaves two nests with the same title, and a later change to the pattern reaches only one of them. To skip an occurrence, use nestr_skip_occurrence; to edit one occurrence, nestr_update_occurrence.

Input schema

{'type': 'object', 'required': ['nestId', 'rrule'], 'properties': {'rrule': {'type': ['string', 'null'], 'description': 'RFC-5545 RRULE string to set recurrence, or null to remove it. Required: pass null explicitly rather than omitting the field.'}, 'nestId': {'type': 'string', 'description': 'Nest ID to set or remove recurrence on'}}}

nestr_skip_occurrence

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_occurrences marked `excluded`, so the skip is a visible decision rather than a silent gap. If the occurrence already exists as a real nest it is deleted along with the exclusion. The first occurrence is the series item itself: skipping it deletes that nest and hands the series to its next occurrence, which is the series nest from then on, and a series with nothing after it ends; the response then carries `restoreId`, and `seriesId` only when the series carries on. Skipping an instant that is already skipped succeeds and changes nothing. This is NOT the same as splitting the series in two: bounding the rule with a COUNT and creating a second recurring nest after the gap leaves two nests with the same title, and a later edit to the pattern reaches only one of them. Use this instead. With scope 'following' it deletes this occurrence and every later one: the series is split at the instant, the occurrences before it keep their history under a rule that now ends there, and cutting at the first occurrence ends the whole series. It answers with `restoreId`, the nest to restore in the Nestr app: restoring it brings back that nest only, and the occurrences deleted with it are restored separately. `instant` must be an occurrence the series actually has: read it from nestr_list_occurrences and pass it through unchanged. An instant off by a second or by a timezone is refused, not silently accepted. A skip needs update rights on the series, plus delete rights on the occurrence if it already exists as a nest. Skipping the first occurrence deletes the series item itself, so it needs delete rights on the series item. It is refused for workspaces and for governance items unless the caller is a governance admin. Scope 'following' needs delete rights on the series and on every occurrence it removes, and a refusal writes nothing.

Destructive

Input schema

{'type': 'object', 'required': ['nestId', 'instant'], 'properties': {'scope': {'enum': ['occurrence', 'following'], 'type': 'string', 'description': "'occurrence' (default) skips this one occurrence and never ends the series. 'following' deletes this occurrence and every later one, keeping the history before it."}, 'nestId': {'type': 'string', 'description': 'The series, or any occurrence of it.'}, 'instant': {'type': ['number', 'string'], 'description': 'Which occurrence: the `instant` value from nestr_list_occurrences, in epoch milliseconds. An ISO-8601 date is accepted only with a Z or an offset, and must be the exact instant the rule produces.'}}}

nestr_start_dm_thread

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 work can read it.

Input schema

{'type': 'object', 'required': ['user'], 'properties': {'user': {'type': 'string', 'description': 'Who to message: user id, username or email'}, 'title': {'type': 'string', 'description': 'Optional title. Defaults to a dated one, as the app uses.'}}}

nestr_update_comment

Update an existing comment's body and/or labels. Supports HTML and @mentions — **mentions MUST be wrapped in literal curly braces** (e.g. `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`); without the braces the user is not notified. When `labels` is provided it REPLACES the existing label set — use nestr_add_label / nestr_remove_label for incremental changes.

Input schema

{'type': 'object', 'required': ['commentId', 'body'], 'properties': {'body': {'type': 'string', 'description': "Updated comment text. Supports HTML and @mentions. Mentions MUST use literal curly braces: `@{userId:roleId}`, NOT `@userId`. Without braces nothing is linked and nobody is notified. Forms: `@{userId:roleId}` (preferred, names the role), `@{userId}`, `@{email}`, `@{circle}` (all fillers in the nearest ancestor circle). The second id MUST be a ROLE or CIRCLE nest, never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. When you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on."}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Optional full set of label IDs for the comment. When provided, this REPLACES the comment's existing labels. To incrementally add or remove a single label without replacing the rest, use nestr_add_label / nestr_remove_label with the commentId as the nestId."}, 'commentId': {'type': 'string', 'description': 'Comment ID to update'}}}

nestr_update_connector

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.

Input schema

{'type': 'object', 'required': ['workspaceId', 'connectorId'], 'properties': {'name': {'type': 'string', 'description': 'Unique connector name within the workspace catalog'}, 'type': {'enum': ['mcp', 'cli', 'api'], 'type': 'string', 'description': 'Transport'}, 'config': {'type': 'object', 'description': 'Per-type transport config, no secret'}, 'enabled': {'type': 'boolean', 'description': 'Switch the connector on or off in this workspace'}, 'exposure': {'type': 'object', 'description': 'Exposure policy: { userAgent, domainGated }'}, 'connectorId': {'type': 'string', 'description': 'ID of the connector to update'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID the connector belongs to'}, 'authStrategy': {'enum': ['secret', 'oauth2'], 'type': 'string', 'description': 'How a principal connects'}, 'capabilities': {'type': 'object', 'description': 'Capability descriptor'}}}

nestr_update_dm_thread

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.

Input schema

{'type': 'object', 'required': ['threadId'], 'properties': {'title': {'type': 'string', 'description': 'New thread title'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The participant list you want, replacing the current one'}, 'threadId': {'type': 'string', 'description': 'Thread id'}, 'completed': {'type': ['boolean', 'null'], 'description': 'true closes the conversation, null reopens it'}}}

nestr_update_inbox_item

Update an inbox item. Set completed:true when processed. Use nestr_update_nest with parentId to move out of inbox. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'data': {'type': 'object', 'description': 'Custom data storage'}, 'title': {'type': 'string', 'description': 'Updated title (plain text, HTML stripped)'}, 'nestId': {'type': 'string', 'description': 'Inbox item ID'}, 'completed': {'type': 'boolean', 'description': 'Mark as completed (processed)'}, 'description': {'type': 'string', 'description': 'Updated description (supports Markdown and HTML)'}}}

nestr_update_nest

Update nest properties. Set parentId to move. Send only what changes. When replacing labels: At most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone): they are the nest's identity and cannot coexist. Only exception: userstory may pair with project. Prefer tensions for governance. See nestr_help('nest-model') for fields and data namespacing.

Input schema

{'type': 'object', 'required': ['nestId'], 'properties': {'due': {'type': 'string', 'description': 'Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time.'}, 'data': {'type': 'object', 'description': "Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."}, 'title': {'type': 'string', 'description': 'New title (plain text, HTML tags stripped)'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': 'User IDs to assign'}, 'fields': {'type': 'object', 'description': "Field updates (e.g., { 'project.status': 'Current' })"}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Label IDs to set (e.g., ['project'] to convert an item into a project)"}, 'nestId': {'type': 'string', 'description': 'Nest ID to update'}, 'domains': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Domain titles for roles/circles (replaces existing). Requires workspaceId.'}, 'purpose': {'type': 'string', 'description': 'Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.'}, 'parentId': {'type': 'string', 'description': 'New parent ID (move nest to different location)'}, 'completed': {'type': 'boolean', 'description': "Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead."}, 'description': {'type': 'string', 'description': 'The primary content field: details, context, acceptance criteria. Structured data goes in fields, progress in comments. Supports Markdown and HTML.'}, 'workspaceId': {'type': 'string', 'description': 'Workspace ID. Required when updating accountabilities or domains.'}, 'accountabilities': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Accountability titles for roles/circles (replaces existing). Requires workspaceId.'}}}

nestr_update_occurrence

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 applied, so if the edit is refused the occurrence may already exist as a real nest, and nestr_list_occurrences shows its `nestId`. The first occurrence is the series item itself and is refused here: change it with nestr_update_nest on the series nest, which also changes occurrences not created yet. A skipped occurrence is refused too, since there is nothing to change. To change the pattern of the whole series, use nestr_set_recurrence instead. `instant` must be an occurrence the series actually has: read it from nestr_list_occurrences and pass it through unchanged.

Input schema

{'type': 'object', 'required': ['nestId', 'instant'], 'properties': {'due': {'type': 'string', 'description': 'Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time.'}, 'data': {'type': 'object', 'description': "Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."}, 'title': {'type': 'string', 'description': 'New title (plain text, HTML tags stripped)'}, 'users': {'type': 'array', 'items': {'type': 'string'}, 'description': 'User IDs to assign'}, 'fields': {'type': 'object', 'description': "Field updates (e.g., { 'project.status': 'Current' })"}, 'labels': {'type': 'array', 'items': {'type': 'string'}, 'description': "Label IDs to set (e.g., ['project'] to convert an item into a project)"}, 'nestId': {'type': 'string', 'description': 'The series, or any occurrence of it.'}, 'instant': {'type': ['number', 'string'], 'description': 'Which occurrence: the `instant` value from nestr_list_occurrences, in epoch milliseconds. An ISO-8601 date is accepted only with a Z or an offset, and must be the exact instant the rule produces.'}, 'purpose': {'type': 'string', 'description': 'Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.'}, 'parentId': {'type': 'string', 'description': 'New parent ID (move nest to different location)'}, 'completed': {'type': 'boolean', 'description': "Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead."}, 'description': {'type': 'string', 'description': 'The primary content field: details, context, acceptance criteria. Structured data goes in fields, progress in comments. Supports Markdown and HTML.'}}}

nestr_update_tension

Update a tension's title, description, feeling, or needs.

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId'], 'properties': {'needs': {'type': 'string', 'description': 'Updated need that is alive (plain text)'}, 'title': {'type': 'string', 'description': 'Updated title — the gap being sensed (plain text)'}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'feeling': {'type': 'string', 'description': 'Updated feeling this tension evokes (plain text)'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}, 'description': {'type': 'string', 'description': 'Updated description — the observable facts (supports Markdown and HTML)'}}}

nestr_update_tension_part_child

Rename an accountability or domain within a proposal part. When the proposal is enacted, the original accountability/domain is updated.

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'partId', 'childId', 'title'], 'properties': {'title': {'type': 'string', 'description': 'Updated title'}, 'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'partId': {'type': 'string', 'description': 'Part ID'}, 'childId': {'type': 'string', 'description': 'Child ID to update'}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_update_tension_status

Submit a tension for voting ('proposed') or retract to 'draft'. Submitting notifies circle members.

Input schema

{'type': 'object', 'required': ['nestId', 'tensionId', 'status'], 'properties': {'nestId': {'type': 'string', 'description': 'ID of the circle or role the tension belongs to'}, 'status': {'enum': ['proposed', 'draft'], 'type': 'string', 'description': "'proposed' to submit for voting, 'draft' to retract back to draft"}, 'tensionId': {'type': 'string', 'description': 'Tension ID'}}}

nestr_upload_file

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.

Input schema

{'type': 'object', 'required': ['nestId', 'name', 'contentType'], 'properties': {'name': {'type': 'string', 'description': 'File name including extension (e.g. "notes.md", "data.csv")'}, 'nestId': {'type': 'string', 'description': 'Nest or comment ID to attach the file to'}, 'content': {'type': 'string', 'description': 'File content as UTF-8 text (for text-native files: .md, .txt, .csv, .json, .html, .svg, code). Stored verbatim. Provide this OR dataBase64.'}, 'dataBase64': {'type': 'string', 'description': 'File bytes, base64-encoded. Provide this OR content.'}, 'contentType': {'type': 'string', 'description': 'MIME type (e.g. "text/markdown", "text/csv", "image/png")'}}}

nestr_user_activity

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.

Read only

Input schema

{'type': 'object', 'required': ['userId'], 'properties': {'limit': {'type': 'number', 'description': 'Max activity items to return (default 50, max 200).'}, 'userId': {'type': 'string', 'description': 'The user whose activity to fetch.'}}}

nestr_workspace_docs

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 own words about how it works, so they outrank your general knowledge about how organisations work; where a document covers the question, quote it rather than reasoning from first principles. Nothing here is guaranteed to exist: a workspace that uploaded nothing returns an empty index, which is an answer, not an error. Auth: any valid token with access to the workspace.

Read only

Input schema

{'type': 'object', 'properties': {'fileId': {'type': 'string', 'description': 'Read one document, from the index or from a search hit.'}, 'offset': {'type': 'number', 'description': "With fileId, continue from a previous nextOffset, or from a search hit's offset."}, 'search': {'type': 'string', 'description': "Find the passages across all the documents that match this. Use words the document would use, not the user's phrasing."}, 'workspaceId': {'type': 'string', 'description': 'Workspace whose documents to read. Omit when you can only reach one.'}}}

mcp

What this MCP does

Tools

Recent tool changes

Similar MCP servers

Stable Baseline

CollHub

mcp

freedom-mcp

Dayze — Life Context

YouSpot

TaScan

Tango