Concepts and referenceTools reference

Tools reference

Every tool Gurusup gives your connected assistant, its parameters and limits, who can use it, what it can see, and which tools change something.

For members and admins who want to know what their assistant can do, and what it should ask before doing it. You never call these tools yourself: your assistant picks a tool from what you ask and sets the values.

ToolGroupChanges something?
initStartNo
healthStartNo
get_profileStartNo
start_company_memory_activityStartRecords a marker only
ask_company_memoryReadNo
search_company_memoryReadNo
retrieve_company_memoryReadNo
add_company_knowledgeWriteYes: adds to Brain
skills_getSkillsNo
skills_publishSkillsYes: submits a skill for approval
request_human_infoPeopleYes: contacts a person
report_issueReport and feedbackRecords a note for the Gurusup team only
send_feedbackReport and feedbackRecords a note for the Gurusup team only
learnOperateNo
One tool for each operation, such as sources_connect or memory_statusOperateDepends on the operation: one that only reads changes nothing, the others change something in Gurusup
memory_progressOperateNo

No tool edits or deletes knowledge that is already saved. The address https://mcp.brain.gurusup.com/mcp lists the 13 tools from init to send_feedback. The three Operate rows come only with https://mcp.brain.gurusup.com/mcp?profile=catalog, the same address with ?profile=catalog, and the tools for agents come only there too. The Operate group lets an assistant run things in Gurusup for you, such as connecting a source or publishing a skill. Besides learn and memory_progress, it has one tool for each operation: see Operate Gurusup from your assistant. To connect an assistant, start with MCP setup. For how a question turns into an answer, see Ask questions.

Who can use the tools

The tools in Start, Read, Write, Skills, People and Report and feedback work the same for an admin, a member and an agent account. None of them needs the admin role. What comes back differs, because every call runs as the account that signed in: it reads only the categories that account can read, plus the restricted sources it was picked for. An agent account is always a member.

The Operate group is different: the tools it offers depend on the role. Some are for admins only. See What each role can do. For what an account can see, read What an agent can see.

Start

init

The first call. Returns Gurusup's rules for the assistant and the list of skills it can use.

  • When the assistant uses it: once per task or session, before the first read.
  • Arguments: none.
  • Who can use it: everyone. The skill list holds only active skills that account may use.
  • Returns: the rules, and a skill list with a total_count. Each skill has these fields when they are set: slug, name, description, categories, version and status. On the catalog address, for a person, init also returns the setup progress (setup_status), a short guide to operating Gurusup from the chat (operate_brain), the list of Gurusup skills (gurusup_skills) and a reminder to reconnect Gurusup if a tool named in the contract is missing from the tool list.

gurusup_skills has two fields. usage tells the assistant that before an action one of these skills covers, it reads that skill with learn. available lists each Gurusup skill with its name and use_when, a sentence on when to use it. They are Gurusup's own guides, not your organization's skills: see learn. The list has 11 skills where agents are available and 8 where they are not.

While your organization's memory is not ready, init gives a person a short setup contract instead of the rules and skill list. On the catalog address it carries the setup progress, the guide and the Gurusup skills, so the assistant can help finish setup from the chat instead of sending you to the web app. The same happens while Gurusup rebuilds or recovers the memory. See MCP troubleshooting.

health

Checks whether Gurusup's backend is reachable.

  • When the assistant uses it: when you ask it to, for example to check a connection.
  • Arguments: none.
  • Who can use it: everyone.
  • Returns: whether the backend is reachable. No company content.

get_profile

Returns the account you are signed in with.

  • When the assistant uses it: when you ask which account a connection uses. ChatGPT also calls it to label connected accounts.
  • Arguments: none.
  • Who can use it: everyone.
  • Returns: your email and an opaque profile ID.

start_company_memory_activity

Creates a record that groups the calls made for one question. Changes no knowledge. Most assistants never call it, because ask_company_memory creates an activity by itself.

  • When the assistant uses it: to start an activity by hand. Each call makes a new record.
  • Arguments: optional label, conversation_id and user_question_hash.
  • Who can use it: everyone.
  • Returns: an activity_id.

Read

These tools search Brain and return evidence. Gurusup does not write the answer: your assistant does, only from what comes back. Gurusup only returns what the account may see.

ask_company_memory

The main tool. Takes a subject and a question and returns evidence from pages of Brain.

  • When the assistant uses it: first, for every company question. Search and retrieve are fallbacks.
  • Who can use it: everyone, within what the account can read.
ArgumentWhat it isRequired
subjectThe company, team, person, product or project the question is about. Several names when the question compares them. null when no specific entity applies or it is not known. It cannot be an empty string.Yes. It can be null, but it cannot be left out.
questionThe information the assistant needs about the subject, 1 to 4,000 charactersYes
activity_idGroups this call with others for the same question, up to 120 charactersNo. Created for you.

subject and question count together toward 4,000 characters. Over that, Gurusup refuses the call with "The subject and question together exceed 4,000 characters. Shorten them and try again." A call without subject is also refused.

subject only focuses the search. It does not filter what you are allowed to see. The assistant is told to take the subject from the conversation, not to invent one, and to ask you first when an unclear subject would stop it from searching usefully.

Gurusup sets everything else: it picks the search mode, looks at more candidate pages than it returns, and keeps up to five pages with up to 4,000 characters each and up to eight facts. The assistant cannot change these. There are no settings for purpose, risk or answer shape.

An assistant connected before subject was added has to refresh the tool's schema before it can ask again. Reconnecting the server does that in most clients.

Returns: the pages Gurusup used, each with its title, its link and the excerpts Gurusup selected, plus the facts behind them, and an activity_id.

  • Every selected excerpt comes back in full, so answers can be long. A fact whose text already appears in an excerpt of the same page is left out.
  • Each fact carries a confidence value. The answer as a whole has no confidence label. The assistant is told not to show scores unless you ask for search diagnostics.
  • A gaps field is always empty, so it does not tell you whether the answer is complete. The assistant judges that from the evidence and your question.
  • If no page answers the question, the answer says so in plain words and carries an evidence_status: evidence_found when there is evidence, evidence_not_relevant when it found matches you may read but none answered the question, and no_evidence_found otherwise. The two empty cases read "The matches found did not answer your question." and "Nothing in company memory answered this question for you.", followed by "Try searching with different terms or a narrower subject, or ask the people who would know."
  • That answer points the assistant to search_company_memory and request_human_info. The assistant still decides whether to ask a person, and it previews first: see Asking a person for missing information.

The assistant is told to pass the returned activity_id to search_company_memory, retrieve_company_memory and request_human_info when those calls follow from this answer, so they count as one question.

search_company_memory

A lighter search that returns candidate matches with a short snippet, not full evidence.

  • When the assistant uses it: as a fallback after ask_company_memory.
  • Who can use it: everyone, within what the account can read.
ArgumentWhat it isDefault and range
queryWhat to search forRequired
top_kNumber of matches5, from 1 to 20
retrieval_modeauto, vector or graphauto
activity_idThe activity this search belongs toOptional
include_diagnosticsReturn the full backend detail, for investigating a searchfalse

Returns: per hit, chunk_id, document_id, title, external_url, snippet and whether it can be retrieved, plus a count. With include_diagnostics, the full backend detail.

retrieve_company_memory

Fetches the full text of pages or passages the assistant picked from a search.

  • When the assistant uses it: when it needs more of a page than an excerpt or snippet gives.
  • Who can use it: everyone, within what the account can read.
ArgumentWhat it isDefault and range
document_ids, chunk_idsThe pages or passages to fetchAt least 1 and at most 3 unique ids in total. Up to 20 with include_diagnostics.
max_chars_per_documentText returned per page12,000, from 1,000 to 50,000
activity_idThe activity this lookup belongs toOptional
include_diagnosticsReturn the full backend detailfalse

Blank ids are dropped and repeated ids count once. Too many ids fails with "Provide at most 3 unique document or chunk ids." (or 20 with diagnostics), and so does a call with none.

Returns: per page, document_id, title, external_url, content, whether it was cut short, and its chunk_ids.

Limits are clamped, not rejected

For search_company_memory and retrieve_company_memory, a number outside its range moves to the nearest allowed value and the call carries on. A top_k of 100 becomes 20, and a max_chars_per_document of 100 becomes 1,000. Ids are the exception, as above. ask_company_memory is stricter: it refuses calls over its limits.

Write

add_company_knowledge

Saves a new fact or note to Brain.

  • When the assistant uses it: only when you ask, confirm, or approve the write in your client, and only for durable company facts. It should not save chat, drafts, temporary preferences, speculation, inference or sensitive personal data, unless you say it is company memory.
  • Who can use it: everyone. It reads nothing.
ArgumentLimitRequired
titleUp to 240 charactersYes
contentUp to 200,000 charactersYes
content_typetext/plain (default) or text/markdownNo
source_urlUp to 1,000 charactersNo
external_idUp to 240 charactersNo
metadataAn objectNo

Returns: a fixed confirmation in Spanish, "Listo." and "En unos minutos esta informacion estara disponible.", with the saved title. It means Gurusup accepted the note, not that it is searchable yet.

  • Gurusup stores your account, your email and your role with the note.
  • Saved knowledge takes a few minutes to show up in answers, and it waits if your organization's usage has run out. See Plan and usage.
  • Gurusup keeps the full text of the note searchable, so a person or a fact mentioned late in a long note can still be found.
  • If adding new content is paused for your organization, Gurusup refuses the note and the tool fails.
  • Knowledge saved through an assistant cannot be edited or removed from the app afterwards.

Skills

skills_get

Loads the full text of one skill the assistant can use.

  • When the assistant uses it: when a skill's description in the init list matches the task.
  • Arguments: slug, the skill's identifier from the list init returns.
  • Who can use it: everyone, for active skills in categories that account can read.
  • Returns: the skill's full text.
  • Counts as a use: yes. Each load adds one to the skill's Usage and sets its Last used time on the Skills page.

skills_publish

Sends a skill you wrote to Gurusup for review.

  • When the assistant uses it: only when you ask.
  • Who can use it: everyone. An admin still has to approve the skill. To publish a new version of a skill that already exists, you have to be its creator or an organization admin.
ArgumentType and limit
slugRequired. Lowercase letters, digits and hyphens, starting with a letter or digit, up to 120 characters. Gurusup lowercases it.
nameRequired. Up to 240 characters.
contentRequired. The skill text, up to 200,000 characters.
descriptionUp to 2,000 characters. The assistant decides whether to load a skill from its description.
tagsA list of text values
categoriesA list of access categories, not topic labels: put topic words in tags. Unknown categories are refused, and so are categories you cannot access. If you leave it out, Gurusup uses metadata.categories, then any tags that name a category, and otherwise general.
versionUp to 80 characters. Defaults to 1.0.0.
assets, scriptsLists of objects the skill carries with it
filesOptional. Files the skill carries, each with a path relative to the skill folder (up to 512 characters) and content_base64, and optionally size and sha256. Base64 is for small text files. Omit it for a Markdown-only skill.
metadataAn object

Returns: a short receipt, not the skill text: the skill's id, slug, name and version, the status of this version, its categories, and the files saved, each with its path, size and sha256. A version that is waiting for review also carries an approval notice. It says that, until an admin approves it, only you can use it, in your personal agents and in the agents you own when you chat with them or run a routine now, and that the whole organization uses it once approved. A member's notice ends with "Ask an admin in your organization to approve it." An admin's notice says "You are an admin, so you can approve it now and make it the organization's version." and carries the skills.change_status call that approves this exact version, so the admin's assistant can run it. If you gave no category, the receipt says "No category was given, so this skill is in general. Pass categories to change it."

If the skill already exists, the current approved version stays in use until the new one is approved. skills_publish cannot approve or archive a skill. An admin can change a skill's status with the skills.change_status operation, see Operate Gurusup from your assistant. Someone who is neither the creator nor an admin gets "Only this skill's creator or an organization administrator can edit it or publish a new version. To publish your own version, use a different skill name." See Skills.

When a category is refused, the assistant reads which one and what to do:

You seeWhat to do
Gurusup rejected these skill categories: "sales-tips". Skills use access categories, not topic labels. Put topic words in tags instead. Use one of: general, sales.Pick a category from the list and move topic words to tags. The names here are examples.
Gurusup rejected these skill categories: "finance". Ask an organization admin to grant access to these categories. Use one of: general, sales.Publish with a listed category, or ask an admin for access to the one you need.
The same message ending "Ask an organization admin to grant access to a category before publishing."You can use no category yet. Ask an admin to grant you one.

Other invalid fields are named the same way, for example "Gurusup could not accept the skill name. Provide a name of 1 to 240 characters." Fix the field and publish again: your local copy is untouched.

A skill, with all its files, can be up to 20 MiB, and up to 512 files. Inline base64 in files is for small text files. For binaries such as images and PDFs, or packages over 1 MiB, the assistant requests a skill upload link (the skills.upload_link operation, which is the tool skills_upload_link) and uploads the skill folder as a ZIP, up to 20 MiB. It works for a new skill and for a new version with the same slug, and the uploaded folder replaces all earlier files. The link lasts 10 minutes. When a skill is too big or a file is not valid base64, the tool points to it:

You seeWhat to do
"This skill is 22.0 MiB and the limit is 20 MiB. Remove or compress large files (the biggest: assets/a.png (3.0 MiB)). Keep your local work. Request a skill upload link, then upload the skill folder as a ZIP (20 MiB package limit). Use the same slug to update an existing skill."Make the skill smaller, then upload it as a ZIP.
"'[path]' could not be read as base64. Keep your local work. Request a skill upload link, then upload the skill folder as a ZIP (20 MiB package limit). Use the same slug to update an existing skill."Upload the skill as a ZIP.
"SKILL.md line 3, column 45, field description: the value contains ': ' and isn't quoted. Wrap the value in double quotes."The SKILL.md header could not be read. The message names the line, column and field, and ends with how to fix it. Fix the header and publish again.

skills.usage

Shows how a skill is used. The assistant runs it as the tool skills_usage. It only reads: it does not load the skill and does not count as a use.

  • When the assistant uses it: when you ask who uses a skill or how often.
  • Arguments: slug, required, the skill's identifier. revision_id, optional, to look at one version.
  • Who can use it: admins and members, with the same access as reading the skill. Members get the skills they can use, admins get any skill.
  • Returns: start_day and end_day, the last 30 UTC days. total, the uses in that window. days, one entry per day with its count, days with no use included. top_users, up to five people or agents that used the skill most, each with a display_name, is_agent and count. history_starts_on is 2026-11-17: the daily counts begin that day and leave out earlier loads, which the Usage total on the Skills page does include.

People

request_human_info

Asks a colleague set up as a contact for company facts Gurusup does not have. Preview first, then dispatch.

  • When the assistant uses it: only for a company fact it needs that is still unsupported after a reasonable, focused search. Not for an unclear question, an optional detail, a fact that simply is not in the answer, an access limit or a service error, and never to get around what you are allowed to see.
  • Who can use it: everyone. It reaches people set up as Gurusup contacts or external contacts. Contacts are set up by an admin, see Contacts.
ArgumentWhat it does
questionRequired. The question to ask, up to 4,000 characters.
dispatchfalse (default) previews and sends nothing. true sends.
activity_idThe activity_id of the answer this follows from. The same one in the preview and the dispatch. Left out only for a new question that uses no retrieved context.
gap_analysisWhat is missing from Gurusup's answer, up to 8,000 characters. Optional.
allowed_channel_typesLimits the channels: call, email, slack, whatsapp. Optional.
requested_contact_idThe contact chosen in the preview. Set on dispatch.
requested_contact_nameA contact you named. Set only when you explicitly asked for that person.
requester_directedtrue only when you asked to be contacted yourself. Requires dispatch true and requested_contact_id.

Returns: in a preview, the contact Gurusup would ask: their name, the channel, the question it would put to them and whether that contact is you. On dispatch, the request runs in the background. Requests you start show under My requests.

Once a request has gone out, the response explains how it stands, without the contact's phone number or email address:

PartWhat it tells you
ChannelWhich channel Gurusup used: call, email, slack or whatsapp.
ReasonWhy that channel, for example the contact prefers it, or the first one was not available so Gurusup used their next allowed option. The channels you allow limit which ones Gurusup uses but do not change the order the contact set. When Gurusup is holding the request on purpose, the reason says why and when, in UTC.
Statescheduled, sent, waiting_for_answer, retrying, delivery_unconfirmed or failed.
What happens nextWhat Gurusup does now, and, when a retry or check is planned, when it will happen. That time is the next delivery check, not a deadline for the person's answer.

scheduled means Gurusup has not tried yet and will do it later. The channel is the one it plans to use. The reason gives the cause and the time in UTC, and the time is when Gurusup will contact the person, not a deadline for their answer. There are three causes:

CauseThe reason reads
The person is already on a call with Gurusup"[Name] is already on a call with us, so we'll call once it ends, around [date and time] UTC."
It is outside the person's contact hours"It's outside [name]'s contact hours, so we'll call at [date and time] UTC."
Gurusup spaces out contact with that person"We space out contact with [name], so we'll call around [date and time] UTC."

When the planned channel is not a call, "call" reads "contact". The assistant relays the reason, so the request is not stuck: it is waiting for that time.

A call to a number saved without a country code fails before it rings, and Gurusup moves to the person's next allowed method. If none is left, the request fails and says "We couldn't call [name] because their phone number needs a country code. Ask an organization admin to add it in Contacts, then ask again." See Contacts.

If a call may or may not have connected, Gurusup checks it again up to three times, about 1, 2 and 4 minutes after the first uncertain result. It does not switch to another channel. If it still cannot confirm, it stops, closes the request as failed and says "We couldn't confirm whether a call reached [name], and automatic checks have stopped. Contact support for help; sending another request could contact them twice." If no allowed channel reached the person, it says "We couldn't reach [name] on the allowed channels. Choose someone else or allow another channel."

Asking a person for missing information

  1. Preview. The assistant calls the tool with dispatch set to false. Nothing is sent. The assistant is told to name only a contact Gurusup returns here, never a person it guessed from your documents or the conversation. If you name a person, Gurusup checks that they are a configured contact. If not, the call fails and the assistant should say so.
  2. Dispatch. After you confirm, the assistant calls it again with dispatch set to true and the contact from the preview. Gurusup contacts that person by their configured method, such as a call or a Slack message. This runs in the background and can take several minutes, so the assistant is told to say so and offer to carry on with something else.

One exception: if you ask to be contacted yourself so you can provide the missing information, that request counts as your confirmation. The assistant previews to check that you are the contact, then dispatches straight away with requester_directed set to true. If the preview picks someone else, it does not send the request to them. If your original request did not ask to be contacted yourself, the assistant waits for your confirmation even when the preview picks you. To be contacted yourself, you need a contact method on your profile.

For failures, see MCP troubleshooting.

Operate Gurusup from your assistant

With https://mcp.brain.gurusup.com/mcp?profile=catalog, an assistant can also run Gurusup for you from the chat: connect a source, build the memory, publish a skill, invite a colleague, read your usage. It does this with learn, memory_progress and one tool for each operation your role allows. Credentials never go through the chat: when a source needs a key, a token or an approval, the assistant gives you a link to Gurusup's own page and you enter it there.

learn

Serves the Gurusup skills: Gurusup's own guides that tell the assistant how to do a job in Gurusup well. They are separate from your organization's skills. They do not appear in the skill list that init returns, skills_get does not load them, and nobody in your organization can edit them. Its title is "Learn How to Do Something in Brain".

  • When the assistant uses it: for onboarding, or before it does something in Gurusup that it has not done before, such as connecting a source, publishing a skill or creating an agent.
  • Arguments: optional topic, and optional page. page reads a reference page of a Gurusup skill when the response lists pages, or a documentation page with the topic documentation.
  • Who can use it: everyone.
  • Returns: without a topic, playbooks, the Gurusup skills available to this connection, each with a topic and what it covers, plus the documentation entry. That is 11 Gurusup skills where agents are available and 8 where they are not. With a topic, that skill as playbook, with pages when it has reference pages. Every answer carries an interface field. It tells the assistant to use the listed individual tool and its schema, and that a tool name is the operation name with its dots replaced by underscores.

The topic is the name of a Gurusup skill from the list. The topic names learn offered before keep working. Some now open one or more Gurusup skills:

TopicWhat it covers
getting-startedRecommend the processes worth turning into skills, then write and publish the skill. Also accepted as onboarding and discover-work.
knowledgeConnect sources, build the memory, skills and conflicting evidence. Also accepted as connect-sources, memory-build, skills and contradictions.
organizationMembers, access and plan usage. Also accepted as members-and-access and usage-and-plan.
source-scopeChoose what Gurusup learns from a source.
agentsCreate or change an agent and its routines, and work with agents: talk to them, handle approvals, follow what they do and put a change back. Also accepted as create-agents and monitor-agents.
appsConnect the apps agents work in and choose which actions run on their own, which wait for approval and which are blocked. Also accepted as agent-apps.
documentationThis documentation. Without page it returns the index. With a page path from the index, for example guides/connect/connectors/slack, it returns that page, up to 60,000 characters.

Where agents are not offered, agents, create-agents, monitor-agents, apps and agent-apps return the list of available skills instead of a skill.

If the documentation is unavailable, the tool says "The documentation is unavailable right now. Continue with what you know."

One tool for each operation

Every operation Gurusup offers is its own tool, listed next to the original tools on the catalog address, https://mcp.brain.gurusup.com/mcp?profile=catalog. The plain address does not list them. An operation has a name made of an area and an action, such as sources.list. Its tool name replaces the dot with an underscore: sources_list. Other examples are sources_connect, jobs_pause, skills_usage and memory_status. Pausing and archiving a routine are their own tools, "Pause Routine" (jobs_pause) and "Archive Routine" (jobs_archive), for admins and members.

Your assistant is offered only the tools your role allows. An admin and a member see different lists, and the list changes when your role changes. There is no fixed number of tools. Gurusup checks the role again when a tool runs. See What each role can do.

Each tool carries a title and a description that say what it does and whether it only reads or changes something. For a tool that changes something and has a Gurusup skill, the description ends with "Before calling, read learn(topic='...')", naming the skill to read first with learn.

A tool takes arguments, an object with the fields of its operation: the fields that point to something at the top level, and the request body under body. It also takes an optional intent, your goal in one short sentence of up to 512 characters, with no sensitive information. A request_id is 8 to 100 characters from letters, digits and . _ : -. The assistant reuses it only to retry the same action after a lost response, so the action does not run twice.

Gurusup checks the arguments against the operation's contract before it runs. It only runs operations from its own list, and it does not run code or free-form requests.

memory_progress

Shows the setup progress card, titled "Knowledge Setup Progress", during first-time memory setup or when you ask to see it. For a question such as "is the memory up to date?" the assistant is told to use the memory.status operation instead (the memory_status tool). The tool only reads: it changes nothing.

What each role can do

Your assistant is offered only the tools the account's role allows, and Gurusup checks the role again when a tool runs. Admins see everything below. Members see the part marked for them.

AreaWhat it coversAdminsMembers
setupSetup progress and the next stepYesYes
memoryBuild status, what each source contributed, the knowledge graphRead, and start or retry the buildRead
sourcesCatalog, list and connections, who can read a source, history estimate and import, webhook sourcesYes, including delete a source, rename a connection, set app enablement and read or set a source's scopeMost reads and connection steps
skillsAvailable skills, details, packages, usage, publish, upload link, editYes, plus review all skills, change a skill's status and draft skillsYes, within the skills they can edit
members, invitations, permissionsRoster, roles, departments, category access, invitationsYesOnly their own name and avatar
contacts, human_infoContacts, and requests for missing informationYesRequests and a few contact actions
contradictionsList, summarize and decide conflicts. The operations use the word contradictions.Yes, and ask a contactList, summarize and decide the conflicts they can read
organizationSettings, name and scheduling timezoneYesRead the settings
organization_agentsThe agents of the organization, as in the Agents table of TeamYesNo
billingPlan, usage and daily usage, read onlyYesAccess status only
activityIngest and query activity, the dashboardYesTheir own activity

Payments and plan changes stay on Gurusup's website: billing is read only here. The Gurusup API checks authorization again on every call, so a tool that is listed can still be refused. When a role does not allow an operation, the assistant is told "This action isn't available for your role. Ask an admin of your organization, or continue with the available tools."

Choose what a source learns

Two operations let an admin choose what Gurusup learns from a source, in the chat. Linear has no screen for it. Attio also has one, on the source.

OperationToolWhat it does
sources.scope_getsources_scope_getReads a source's choices and their real names. Takes connection_id, and optionally counts and object. It counts only when asked, and returns without counts when counting takes too long.
sources.scope_setsources_scope_setTakes rows and a required dry_run. With dry_run true it previews what starts and what stops updating, with counts and up to five example names per object. With dry_run false it saves.

Both are for admins only. For anyone else the answer is "Ask an organization admin to choose what this source shares." They work for Attio, per object (companies, deals, people and custom objects), and for Linear, per team. On another source the answer is "This source does not offer scope choices. Choose a supported source such as Linear."

  • Each object is All or Custom. All includes future records. Custom includes only the values you pick, and several picks combine with "or". For Attio the values are select and status options, yes or no checkboxes, owners, a list with an optional stage, and saved views.
  • What leaves the scope stays in memory but stops updating. A record that starts to match comes in with its next change. Saving never imports history: use Import history for older records.
  • Counts stop at 10,000. A count that stops there is a minimum.
  • The assistant is told to preview with dry_run first, show what starts and stops, and save only after you confirm.

For the Attio screen and what the default does, see Connect Attio.

Create or change an agent from the chat

Before your assistant creates an agent or changes its goal, skills or routines, it reads Gurusup's guide for agents with learn (catalog address only). It follows that guide in these ways:

  • It looks at your agents first. If one already covers the area, it adds a skill to that agent instead of creating another.
  • The goal says what the agent is for. The steps of the work go in the skills assigned to the agent. Before saving a new goal, it tests it on a real example, as described below.
  • If you want to talk before choosing a purpose, it can create the agent without a goal. The agent then proposes its name and goal in its own chat, as described in Review agent setup changes.
  • A routine the assistant suggests is not created until you say yes.
  • The tools that save a routine are titled "Create an Agent Routine" and "Update an Agent Routine". A change made by an agent can pause the routine.
  • A routine saved from your assistant starts paused. It runs on its own only after you turn it on, and the assistant is guided to offer a first run you can read before you decide. A routine that changes websites is the exception: it needs one run that you review. If it is turned on without that review, its first scheduled run does not make the change and the routine pauses.
  • Before it creates a routine, it is guided to try the process once in the chat with the agent. It is also guided to change an existing routine instead of creating a new one, and not to split a routine into several without asking you.
  • When you say a routine must do nothing outside certain days or hours, the assistant is guided to save those limits in the routine's schedule, so it does not start outside them. Hours that only limit notifications do not restrict when it runs.
  • This is guidance for the assistant, not a guarantee.

Test an agent's goal before saving it

When you ask your assistant to change the goal of an agent, it tries the new goal first. Two operations do this, and the saved agent stays as it is until you agree.

OperationToolWhat it does
agents.test_goalagents_test_goalTakes the new goal (up to 32,000 characters) and a real example message (up to 8,000 characters). It runs the agent once with that goal, without saving it, and returns an id, the conversation and a status.
agents.goal_testagents_goal_testTakes the agent and the test id, and returns the status (queued, running, waiting, succeeded, failed or stopped), the goal that was tried and the agent's reply.
  • The run happens in a conversation titled "Goal test". Only the owner of the agent can start a test or read its result, and only the owner sees that conversation. A goal test takes one example: to try another message, start a new test.
  • Actions that reach outside Gurusup keep the approvals the agent already has.
  • To save the goal, the assistant calls agents.update with the test's goal_test_id. If you chose to skip the test, it sends untested as true instead. Gurusup keeps a record of which of the two was used.
  • An agent runs one goal test at a time. Asking again with the same goal and example while it runs returns that test. A different goal or example is refused until the running test finishes or you stop it in its conversation.
  • The test has to match: the same goal, an agent whose tools, skills and other settings have not changed since, and a run that finished successfully. Renaming the agent, changing its avatar or pausing it does not make a test out of date.
  • Only changes made through an assistant need this. Changing the goal in the app does not ask for a test, and neither does Put it back in an agent's history.
The assistant seesWhat it means
"Test this goal before saving it: run agents.test_goal with the new goal and a real example, show the result, then save with its goal_test_id. If the owner chose to skip the test, save with untested set to true."The goal changed and the update carried neither a test nor untested, or carried both.
"This test was for a different goal. Test the new goal before saving it."The goal sent is not the one that was tested.
"This agent's tools, skills or settings changed after the test, so its result may differ. Test the goal again, then save it together with any other changes."Someone changed the agent's tools, skills or other settings after the test ran.
"Another goal test for this agent is still running. Wait for its result, or stop it in its conversation, then test this goal."The agent already has a goal test running for a different goal or example.
"This goal test hasn't finished successfully. Wait for it to finish or test the goal again."The test is still running, or it failed or was stopped.
"Only the owner can test a new goal for this agent. Ask them to do it."You are not the owner of the agent.
"Only the owner can see this goal test. Ask them if you need its result."You tried to read a test of an agent you do not own.
"This goal test already has an example. Start a new test to try another message."A second message was sent in the same test.
"This goal test is unavailable. Start a new test."The test id does not exist for you and this agent.

Connect a source from the chat

The assistant uses the tools sources_catalog, sources_connections and sources_connect. When a source needs a key, a token or an approval, sources_connect returns a link to Gurusup's connection page, valid for 30 minutes. A client that supports it opens the link; you enter the credential there and go back to the chat. A webhook source works the same way: you create it on Gurusup's page, copy its address to your system, and the assistant sends JSON to it with sources.add_document.

For an app that can be personal, such as tl;dv, sources_connect takes scope: organization or personal. Without it, it prepares your own account when you can, otherwise the organization's for an admin. A member never connects the organization's. requested_scope in the result says which.

A source connected this way learns from then on and never imports older history by itself. To bring it in, the assistant reads sources.history_estimate, asks for your agreement because the import uses your usage, and then runs sources.history_import. The old automatic_history field is ignored, and sources.backfill no longer exists.

Apps for agents work with a link too. apps.connect sends you to Gurusup's connection page to sign in or enter the credential, or reuses an account you already chose, and the assistant confirms the account and scope afterwards. The scope is personal unless you ask for an organization account, which only admins can connect. To do it in the app, see Connect apps for agents.

To tell connections of one app apart, an assistant renames one with sources_rename_connection: an admin for an organization connection, the owner for a personal one such as a tl;dv key. It takes the connection_id from sources.connections and, in body, a new name of 1 to 120 characters, like Rename on the source's page: see Rename a connection.

When an operation fails

The assistant relays Gurusup's own message when there is one. These are the ones it can see.

The assistant seesWhat it means
"Review the operation's required fields and values with discover, then submit again."The arguments do not match the tool's contract. The assistant checks the schema the tool lists and tries again.
"This action isn't available in your Gurusup connection. Continue with the available tools."The address your assistant connected with does not list that tool. The plain address has only the 13 original tools.
"This action isn't available for your role. Ask an admin of your organization, or continue with the available tools."Your role does not allow the tool.
"This operation is unavailable. Open Gurusup to check your access."The operation is not open to your account, or your access changed.
"Your access to this action has changed. Open Gurusup to check your access."Your role or membership changed.
"Only an organization admin can do this. Ask an admin in your organization to do it."A member reached an operation only admins can run.
"This needs an organization administrator. Ask an admin to do it, or to change your role."An admin-only operation, refused with 403.
"Gurusup couldn't find that. List it again to get the current one."A reference is out of date (404).
"This changed or is already in progress. Load its current state before acting again."A conflict (409).
"The change was applied, but Gurusup could not read its details. Verify the change with the matching read operation. Do not retry the write."The change went through. Check it with a read before doing anything again.
"Gurusup couldn't finish this because of a problem on our side. Nothing you set up was lost." followed by a line that points to supportIt failed on Gurusup's side. A failure between Gurusup's own services shows this message too, so it is not a sign-in problem and you do not need to reconnect. Contact support if it keeps happening.
"This action doesn't support HappyScribe content. Search company memory for the call you need."The assistant tried to browse or import pages from a source other than Notion. Only Notion has that. For any other app, for example HappyScribe, the assistant should search company memory instead. For apps it does not name, the text reads "This action doesn't support this app's content. Search company memory for information already collected from this app."

Report and feedback

Both tools record a note for the Gurusup team. Neither changes what Brain holds or contacts anyone, and neither is for wrong company facts: for those, tell your admin, or see Resolve conflicts.

report_issue

Reports a failure the assistant can point to.

  • When the assistant uses it: once a failure is confirmed, not on first suspicion. It needs no permission and tells you in one line.
  • Who can use it: everyone.
ArgumentWhat it isLimit
categoryRequired. See below.
observedRequired. What happened.2,000 characters
expectedRequired. What should have happened.2,000 characters
activity_idOptional
tool_nameOptional
user_requestOptional500 characters
error_messageOptional2,000 characters
CategoryUse
missing_informationYou say something exists and Gurusup did not return it
wrong_answerAn answer contradicts its own evidence
tool_errorA tool failed
access_problemSomething went wrong when the assistant tried to read what you are allowed to see. Not for results that are simply hidden from you.

send_feedback

Suggests an improvement when nothing failed.

  • When the assistant uses it: once, at the end of the task.
  • Who can use it: everyone.
ArgumentWhat it isLimit
summaryRequired. The suggestion.2,000 characters
originRequired. user when the idea is yours, agent when it is the assistant's.
contextOptional1,000 characters
blockedOptional. Set when the gap stopped the task.
activity_idOptional

What both return

Text over a limit is cut to fit, not refused. A report includes your organization and account, what the assistant wrote, the activity_id if there is one, the name and version of the assistant app, and an ID for the connection session and for the Gurusup release. Reports do not appear anywhere in the app. Gurusup counts a report as recorded only when it gets a receipt for it. Without one, the tool answers unconfirmed, and the assistant is told to carry on with your task, not to say the report was saved or that support was contacted, and not to send it again. A report is never sent under another account.

How tools are marked

Every tool has a title and marks that say whether it reads or writes. Your client can use them to decide when to ask for your approval. The titles are exactly what Gurusup sends, so your client may show them.

Tool (title)Read-onlyDestructiveNotes
init (Initialize GuruSup Brain)YesNo
health (Check GuruSup Brain Health)YesNo
get_profile (Get Signed-in Profile)YesNo
start_company_memory_activity (Start Company Memory Activity)YesNoEach call makes a new record
ask_company_memory (Ask Company Memory)YesNo
search_company_memory (Search Company Memory)YesNo
retrieve_company_memory (Retrieve Company Memory Evidence)YesNo
skills_get (Get Company Skill)YesNo
add_company_knowledge (Add Company Knowledge)NoNo
report_issue (Report a Gurusup Issue)NoNo
send_feedback (Send Gurusup Feedback)NoNo
skills_publish (Publish Company Skill)NoYes
request_human_info (Request Information from a Person)NoYesReaches outside Gurusup: can send a message or place a call
learn (Learn How to Do Something in Brain)YesNo
An operation tool, such as sources_connect (the title is the operation's summary)Yes, when the operation only readsOnly when it changes something, and not when it only adds something new, such as connecting a source or creating an agentDoes only what its operation does, for example connect or disconnect a source, change a role or remove a member
memory_progress (Knowledge Setup Progress)YesNoShows a card

Slow answers and failures

A slow answer can take minutes. Gurusup waits up to 10 minutes for its own backend before giving up, so a tool that seems stuck is often still working. See MCP troubleshooting.

A failed call comes back to the assistant as an error that starts with "Error executing tool" and the tool's name. What follows depends on where it failed. See How errors look.