> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported tools

> Learn what you can do with folk MCP tools

Once you've connected folk MCP, AI assistants can use these tools to search, create, and manage content in your folk workspace.

These tools work seamlessly together through prompts, and their real power comes from combining them. With a single prompt, you can search your workspace, create new contacts from the results, and update fields across multiple records.

<AccordionGroup>
  <Accordion title="Get current user">
    `folk_get_current_user`

    <Badge color="green">Read-only</Badge> <Badge color="blue">Idempotent</Badge>

    Returns the identity of the authenticated folk user for this MCP session:
    their id, email, and fullName. Call once per session when you need to
    attribute an action to the current user (e.g. assigning a task, filtering
    by owner). Do not call to look up other workspace members — use the members
    array from folk\_get\_workspace\_schema instead. Does not return role, permissions,
    or plan information.
  </Accordion>

  <Accordion title="Get the workspace structure">
    `folk_get_workspace_structure`

    <Badge color="green">Read-only</Badge>

    Retrieves the complete structure of the folk workspace: groups, entity types per group,
    native fields (person/company/object), custom field definitions (names, types, allowed values), pipeline views,
    and workspace members. Call at the start of every fresh session before reading or writing any workspace data —
    the schema may have changed since the last session (new groups, renamed fields, updated pipeline stages).
    Do not call again within the same session unless the user explicitly changes the workspace structure.
    Does not return contact data, notes, or interaction history.
  </Accordion>

  <Accordion title="Search companies">
    `folk_search_companies`

    <Badge color="green">Read-only</Badge>

    Search companies in the folk workspace using one or more filters.

    Use for:

    * finding a specific company (e.g. "Acme Corp")
    * filtering companies by native fields, groups, creators, or custom fields

    Do not call with an empty filter.

    Filter shape:
    `{
          "<fieldName>": {
            "<operator>": <operand>
          }
        }`

    Field categories:

    * Text fields (name, description, industry, emails, phones, urls, addresses, custom fields):
      operators: eq, not\_eq, like, not\_like, empty, not\_empty

    * Numeric/date fields (fundingRaised, lastFundingDate, createdAt, custom fields):
      operators: eq, not\_eq, gt, lt, empty, not\_empty

    * Single and multi select fields (custom fields):
      operators: in, not\_in, empty, not\_empty

    * Reference fields (groups, createdBy):
      operators: in, not\_in, all, empty, not\_empty

    Important operand rules:

    * eq / like / gt / lt → operand is usually a plain string
      Example: `{ "name": { "eq": "John Doe" } }`

    * empty / not\_empty → operand MUST be an empty string
      Example: `{ "industry": { "empty": "" } }`

    * in / not\_in / all → operand MUST be an object with a single attribute being a single string or an array of string
      Example: `{ "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }`

    * SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object)
      Examples:
      `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }`
      `{ "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }`

    * Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string
      Examples:
      `{ "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } }`
      `{ "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } }`
      `{ "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }`

    Custom fields: Use key format `customFieldValues.<groupId>.<fieldLabel>`
    Example:
    `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }`

    Use combinator for AND/OR logic.
    Returns paginated company objects.
    Use folk\_get\_company if companyId is already known.
  </Accordion>

  <Accordion title="Get a company">
    `folk_get_company`

    <Badge color="green">Read-only</Badge>

    Fetch a single company by companyId.
    Use when you already have a companyId from a previous search\_companies call or from another tool response.
    Do not use to find or look up a company by name, domain, or other attribute — use search\_companies instead.
    Returns the full company object: native fields (name, description, industry, foundationYear, fundingRaised, lastFundingDate, employeeRange), group memberships, and custom field values per group.
  </Accordion>

  <Accordion title="Create a company">
    `folk_create_company`

    <Badge color="yellow">Read-write</Badge>

    Create a new company in the folk workspace. Provide at least a name to identify the company.
    Multi-value fields (emails, phones, addresses, urls) accept plain arrays — the first element becomes the primary value.
    Use groups (array of { id }) to add the company to one or more groups at creation time.
    Use customFieldValues to set custom field values, keyed by group id then field name — every group id used there must also be present in groups.
    Returns the full company object.
  </Accordion>

  <Accordion title="Update a company">
    `folk_update_company`

    <Badge color="yellow">Read-write</Badge> <Badge color="red">Destructive</Badge>

    Update an existing company by id. Partial update — omit any field you don't want to change. Scalar fields (name, description, industry, foundationYear, fundingRaised, lastFundingDate, employeeRange): provide the new value directly.
    Multi-value fields (emails, phones, addresses, urls) require a prefixed operation param — add/remove will be mutually exclusive to set operation.

    * add\* — append values to the existing list (e.g. addEmails: \['[new@acme.com](mailto:new@acme.com)'])
    * remove\* — remove specific values from the existing list
    * set\* — replace the entire list with the provided values.
      To add the company to a group, use addGroupIds. Groups cannot be removed via this tool.
      Use customFieldValues to update custom field values, keyed by group id then field label.
      Returns only companyId — call get\_company if you need the updated full object.
  </Accordion>

  <Accordion title="Search people">
    `folk_search_people`

    <Badge color="green">Read-only</Badge>

    Search people in the folk workspace using one or more filters.

    Use for:

    * finding a specific person (e.g. "John Doe")
    * filtering people by native fields, groups, companies, creators, or custom fields

    Do not call with an empty filter.

    Filter shape:
    `{
          "<fieldName>": {
            "<operator>": <operand>
          }
        }`

    Field categories:

    * Text fields (fullName, firstName, lastName, jobTitle, description, emails, phones, urls, addresses, custom fields):
      operators: eq, not\_eq, like, not\_like, empty, not\_empty

    * Numeric/date fields (birthday, createdAt, interactionMetadata.workspace.lastInteractedAt, custom fields):
      operators: eq, not\_eq, gt, lt, empty, not\_empty

    * SingleSelect/MultiSelect fields (custom fields):
      operators: in, not\_in, empty, not\_empty

    * Reference fields (groups, companies, createdBy):
      operators: in, not\_in, all, empty, not\_empty

    Important operand rules:

    * eq / like / gt / lt → operand is usually a plain string
      Example: `{ "fullName": { "eq": "John Doe" } }`

    * empty / not\_empty → operand MUST be an empty string
      Example: `{ "jobTitle": { "empty": "" } }`

    * in / not\_in / all → operand MUST be an object with a single attribute being a single string or an array of string
      Example: `{ "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }`

    * SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object)
      Examples:
      `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }`
      `{ "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }`

    * Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string
      Examples:
      `{ "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } }`
      `{ "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } }`
      `{ "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }`

    Custom fields: Use key format `customFieldValues.<groupId>.<fieldLabel>`
    Example:
    `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }`

    Use combinator for AND/OR logic.
    Returns paginated person objects.
    Use folk\_get\_person if personId is already known.
  </Accordion>

  <Accordion title="Get a person">
    `folk_get_person`

    <Badge color="green">Read-only</Badge>

    Fetch a single person by their folk person id and return the full person payload (names, emails, phones, addresses, urls, companies, groups, custom field values, interaction metadata). Use this only when you already have the person id (e.g. from folk\_search\_people or a previous folk\_create\_person). Do not use it to look up a person by name or email — that is what folk\_search\_people is for.
  </Accordion>

  <Accordion title="Create a person">
    `folk_create_person`

    <Badge color="yellow">Read-write</Badge>

    Create a new person in the folk workspace and return the full created person. Provide at least a name (fullName, or firstName/lastName) OR at least one email. For every multi-value field (emails, phones, addresses, urls), the first element is treated as the primary value. companyIds links the person to existing companies (call get\_workspace\_structure / search to obtain ids). groupIds adds the person to groups at creation. customFieldValues are keyed by group id, then by field name.
  </Accordion>

  <Accordion title="Update a person">
    `folk_update_person`

    <Badge color="yellow">Read-write</Badge> <Badge color="red">Destructive</Badge>

    Update an existing person in the folk workspace. Only the fields you provide are changed — omitted fields are left untouched. For multi-value fields (emails, phones, addresses, urls, companyIds) use addX / removeX for incremental changes or setX to replace the full list. addGroupIds is additive only (groups are never removed via this tool). customFieldValues are keyed by group id, then by field name.
  </Accordion>

  <Accordion title="Search objects">
    `folk_search_objects`

    <Badge color="green">Read-only</Badge>

    Search objects (e.g. deals) in the folk workspace using one or more filters.

    Use for:

    * finding a specific object (e.g. "Project Alpha")
    * filtering objects by name, creation date, creator, or custom fields

    Do not call with an empty filter.
    Use folk\_get\_workspace\_structure first to discover available groupIds and object types.

    Filter shape:
    `{
          "<fieldName>": {
            "<operator>": <operand>
          }
        }`

    Field categories:

    * Text fields (name):
      operators: eq, not\_eq, like, not\_like, empty, not\_empty

    * Date fields (createdAt):
      operators: eq, not\_eq, gt, lt, empty, not\_empty

    * Reference fields (createdBy):
      operators: in, not\_in, empty, not\_empty

    Important operand rules:

    * eq / like / gt / lt → operand is usually a plain string
      Example: `{ "name": { "eq": "Project Alpha" } }`

    * empty / not\_empty → operand MUST be an empty string
      Example: `{ "name": { "empty": "" } }`

    * in / not\_in / all → operand MUST be an object with a single attribute being a single string or an array of string
      Example: `{ "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }`

    * SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object)
      Examples:
      `{ "customFieldValues.Status": { "in": "Active" } }`
      `{ "customFieldValues.Tags": { "in": ["B2C","B2B"] } }`

    * Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string
      Examples:
      `{ "customFieldValues.Relationships": { "in": { "id": "per_aaa" } } }`
      `{ "customFieldValues.Owner": { "in": { "id": "usr_aaa" } } }`

    Custom fields: Use key format `customFieldValues.<fieldLabel>`
    Example:
    `{ "customFieldValues.Status": { "in": "Active" } }`

    Use combinator for AND/OR logic.
    Returns paginated object payloads with name, people, companies, customFieldValues.
    Use folk\_get\_object if objectId is already known.
  </Accordion>

  <Accordion title="Get an object">
    `folk_get_object`

    <Badge color="green">Read-only</Badge>

    Fetch a single object (e.g. deal) by its ID within a specific group and object type.
    Use when you already have an objectId from a previous folk\_search\_objects or folk\_create\_object call.
    Returns the full object: name, people, companies, createdAt, createdBy, customFieldValues.
  </Accordion>

  <Accordion title="Create an object">
    `folk_create_object`

    <Badge color="yellow">Read-write</Badge>

    Create a new object (e.g. deal) within a specific group and object type in the folk workspace.
    Use folk\_get\_workspace\_structure first to discover available groupIds and object types.
    Provide name, and optionally link people and companies by their folk IDs.
    customFieldValues is a flat record keyed by field name (e.g. `{ "Status": "Active" }`) — no group nesting needed.
    Returns the full created object.
  </Accordion>

  <Accordion title="Update an object">
    `folk_update_object`

    <Badge color="yellow">Read-write</Badge> <Badge color="red">Destructive</Badge>

    Update an existing object (e.g. deal) in the folk workspace. Partial update — omit any field you don't want to change.
    name: provide new value to rename.
    people / companies: providing a list REPLACES all current associations. Omit to leave unchanged.
    customFieldValues: flat record keyed by field name. Passing null or empty array unsets the value.
    Returns only objectId — call folk\_get\_object if you need the updated full object.
  </Accordion>

  <Accordion title="Search notes">
    `folk_search_notes`

    <Badge color="green">Read-only</Badge>

    Search notes in the folk workspace.

    Use for:

    * listing recent notes across the workspace (no filters needed)
    * finding notes attached to a specific contact or company
    * filtering notes by creation date or content

    Parameters:

    * entityId (optional): filter by entity. Format `per_<uuid>` for a person, `com_<uuid>` for a company, `obj_<uuid>` for objects.
    * query (optional): full-text search against note content.
    * createdAfter (optional): ISO 8601 timestamp — return only notes created after this date.
    * createdBefore (optional): ISO 8601 timestamp — return only notes created before this date.
    * limit / cursor: pagination.

    Returns paginated note objects with nextCursor when more pages exist.
  </Accordion>

  <Accordion title="Create a note">
    `folk_create_note`

    <Badge color="yellow">Read-write</Badge>

    Create a new note linked to a person or company in the folk workspace.

    entity.id: required — the entity to attach the note to.
    Format: `per_<uuid>` for a person, `com_<uuid>` for a company and `obj_<uuid>` for an object .
    Obtain entity IDs from folk\_search\_people, folk\_search\_companies or folk\_search\_objects.
    content: required — note body in markdown (max 100 000 chars).
    visibility: "public" (visible to all workspace members) or "private" (visible only to you). Defaults to "public".
    parentNote.id: optional — attach as a reply to an existing note on the same entity.

    Returns the full created note object.
  </Accordion>

  <Accordion title="Update a note">
    `folk_update_note`

    <Badge color="yellow">Read-write</Badge> <Badge color="red">Destructive</Badge>

    Update the content or visibility of an existing note.

    Partial update — omit any field you do not want to change.
    noteId: the note to update (format: `nte_<uuid>`). Obtain from folk\_search\_notes.
    content: new markdown body (optional).
    visibility: "public" or "private" (optional).

    Returns only noteId. Call folk\_search\_notes to retrieve the updated note object.
    Note: only user-authored notes can be updated.
  </Accordion>

  <Accordion title="Create an interaction">
    `folk_create_interaction`

    <Badge color="yellow">Read-write</Badge>

    Log a past interaction (a recorded touchpoint such as a call, meeting, or message) with a person or company.

    Use for:

    * recording that a conversation or meeting happened (e.g. "Had a coffee with John Doe")

    Only manually logged interactions can be created here. Imported interactions (email, calendar, WhatsApp) sync automatically from connected sources and cannot be created with this tool.

    Required:

    * entity.id — the person (`per_<uuid>`) or company (`com_<uuid>`) the interaction is linked to
    * dateTime — when the interaction happened, as an ISO 8601 timestamp (e.g. "2025-07-17T09:00:00.000Z")
    * title — short summary of the interaction
    * content — the multi-line body of the interaction
    * activityType — the kind of interaction: a predefined activity (call, meeting, message, coffee, lunch, event, drink), a messaging app (slack, whatsapp, linkedin, telegram, etc.), or a single emoji

    Returns the full created logged interaction.
  </Accordion>
</AccordionGroup>