Tallyfy Workflow Automation

Complete a process kickoff form to mark it as submitted. REQUIRED: 'run_id' (32-char hex process ID).

Mark a standalone (one-off) task as complete. REQUIRED: 'task_id'. Use THIS tool (not complete_task) for a task created via create_standalone_task: one that has no run_id you already know. It works whether or not the task turns out to be linked to a process or a hidden container run (from separate_task_for_each_assignee fan-out creation): it looks the task up first and routes the request correctly either way, so you never need to resolve run_id yourself. APPROVAL TASKS need is_approved, same rule as complete_task: task_type="approval" -> MUST pass is_approved=True or is_approved=False an…

Mark a task as complete. REQUIRED: 'run_id' (32-char hex process ID) and 'task_id'. APPROVAL TASKS need is_approved: If the task's task_type is "approval", you MUST pass is_approved=True (approve) or is_approved=False (reject). api-v2 returns HTTP 422 "The is approved field is required" if you omit it on an approval task. The requirement is gated on the task's OWN task_type, not on its parent step_type (the two can differ). Read task_type first via get_tasks_for_process or get_task (both return it). task_type="task" -> do NOT pass is_approved (regular completion) …

Create conditional automation (if-then rules). A conditional SECTION ("C only if amount > 5000") is ONE show rule: a show action hides its step at launch until the condition is met; no hide rule is needed. Automations need a Pro plan or trial. REQUIRED: 'template_id' + 'automation_data' (dict with `conditions`+`actions`). action_type CONSTRAINS action_verb: visibility -> show | hide deadline -> deadline status -> reopen webhook -> emit_webhook assignment -> assign | assign_only | unassign | clear_assignees conditionable_type: step | field | kickoff (auto-resolved) Step ops: …

Create a new folder in the organization. REQUIRED: 'name' (folder name, max 32 chars). Optional: - 'folder_type': 'checklist' (DEFAULT, a folder that holds templates/blueprints) or 'run' (a folder that holds processes). Also accepts the aliases template/blueprint -> checklist and process -> run. - 'parent_id': 32-char hex ID of a parent folder, for nesting. The parent MUST be the same folder_type. CHOOSING folder_type MATTERS. It is fixed at creation and cannot be changed later: - To file PROCESSES into it (add_object_to_folder(object_type="run"), or get_organization_runs(folder=...…

Create a new group (team) in the organization. REQUIRED: 'name' (group name, max 200 chars, must be unique in the organization) AND 'description' (non-empty string). The API rejects a create without a description, so ask the user for one, or pass a short factual summary of the group's purpose, rather than omitting it. Optional: 'members' (list of numeric member user IDs), 'guests' (list of guest emails). CORRECT usage: create_group(name="Finance", description="Finance department approvers") create_group(name="Onboarding buddies", description="Volunteers who mentor new hires", …

Create a new guest (external collaborator) in the organization. REQUIRED: 'email' (valid email). That is the only required field. Optional but STRONGLY PREFERRED: 'first_name', 'last_name' (max 200 chars each). The API accepts a guest with neither, and a nameless guest shows as just an email address everywhere in Tallyfy. Supply them when you know them; do NOT invent placeholders and do not stall to interrogate the user for names you were not given. Optional: 'phone_1' (primary phone, max 20 chars), 'phone_2' (secondary phone, max 20 chars), 'company_name' (max 200 chars). NOTE the phone p…

Create a standalone (one-off) task with explicit structured fields. NOTE: no process is created by default (is_oneoff_task: true), so the task will not appear in get_organization_runs. Only the fan-out flag below creates one. REQUIRED: title, deadline, at least one assignee. If deadline or assignee is missing, ASK the user before calling. DEADLINE: exact LOCAL time, 'YYYY-MM-DD HH:MM' (e.g. '2026-10-02 17:00'). Not natural language, not UTC: the server converts with the org timezone. TASK TYPE: task (default) | approval | expiring (auto-completes at deadline) | 'email' (a DRAFT: a human re…

Create a new tag in the organization. REQUIRED: 'title' (tag name). Optional: 'color', which must be EXACTLY 7 characters as #RRGGBB (e.g. '#FF5733'). api-v2 enforces size:7, so shorthand ('#F53'), alpha ('#FF5733AA') and named colors ('red') are all rejected.

Create a new template (the reusable recipe - Tallyfy's checklist/blueprint object). Step 1 of the build chain: then add_step_to_template per step, add_form_field_to_step for in-step data, add_kickoff_field for pre-launch data, create_automation_rule for if-then logic, and offer launch_process for a test run named after a real example. BEFORE calling this: mirror the user's goal in one plain-English sentence, sketch the likely steps, and ask only the 2-3 questions that change the design (where does this data live today; how many per month and how much do they vary; who does what). Never create…

Remove an automation rule from a workflow template. REQUIRED: 'template_id' and 'automation_id'.

Delete a folder permanently. REQUIRED: 'folder_id'. Contents are NOT deleted. Processes/templates are moved out first.

Delete a form field from a step. REQUIRED: 'template_id', 'step_id', and 'field_id'. WARNING: the API does not stop this when an automation depends on the field. The delete goes through, answers 204 No Content, and every automation rule condition pointing at this field is removed along with it, silently, with nothing in the response saying so. The automation itself survives without that condition, so a rule that used to fire on this field can start behaving differently. This cannot be undone. PRE-FLIGHT: call analyze_template_automations first and look for a condition whose 'conditionable_type…

Delete a group from the organization permanently. REQUIRED: 'group_id'. This action cannot be undone.

Delete a kickoff (prerun) field from a template. REQUIRED: 'template_id' and 'field_id'. WARNING: Deleting a kickoff field removes it permanently and drops all collected data for that field across existing process runs. This cannot be undone. WARNING: the API does not stop this when an automation depends on the field. The delete goes through, answers 204 No Content, and every automation rule condition pointing at this field is removed along with it, silently, with nothing in the response saying so. The automation itself survives without that condition, so a rule that used to fire on this fi…

Delete a scheduled job so it never runs again. REQUIRED: 'job_id'. Confirm with the user before calling it: these tools cannot bring a deleted job back. Processes the job already launched are not touched. The tool reads the job back afterwards and reports it deleted only when Tallyfy no longer finds it. To stop a job for a while instead, use pause_scheduled_job.

Permanently delete a standalone (one-off) task. REQUIRED: 'task_id'. This cannot be undone. The task, its form fields and their answers are removed, and Tallyfy has no restore for a deleted task. Confirm with the user before calling it. Use it to clean up a task made with create_standalone_task, for example one created for testing. A task inside a process is NOT deleted this way, and neither is a one-off task linked to a process (any task with a run_id, including the tasks separate_task_for_each_assignee creates). The tool reads the task first and refuses those before anything is deleted. T…

Delete a step from a template PERMANENTLY. REQUIRED: 'template_id' and 'step_id'. Unlike archiving a template, this is a true hard delete with no restore endpoint. It cannot be undone. THE API BLOCKS THE DELETE INSTEAD OF CASCADING. Orphaned automation rules are NOT pruned server-side. The request is REJECTED with an error if either of these holds: - any automation rule references the step (as a rule's `conditionable_id`, or as the target of a then-action) → "Cannot delete this step because there are rules dependent on it." - any other step's deadline is anchored to this step → "Cann…

Delete a tag from the organization permanently. REQUIRED: 'tag_id'. This action cannot be undone.

Delete a comment from a task. REQUIRED: 'task_id' and 'comment_id'. Optional: 'run_id' (pass if available). This action cannot be undone.

ARCHIVE a template. REQUIRED: 'template_id'. The TEMPLATE itself is recoverable. It is archived (hidden from default template lists), its steps, form fields and automation rules are preserved, and Tallyfy exposes a restore endpoint that brings the template back. ONE PART IS NOT RECOVERABLE. Say so; do not reassure the user that this is safe. Archiving permanently removes this template's embedded references from the BODY CONTENT of every OTHER template and step in the organization. Restoring the template does NOT put them back, and no restore path in the product recovers them. Processes alrea…

Disable a guest account. REQUIRED: 'email' (valid email). This prevents the guest from accessing the organization.

Disable a user account. REQUIRED: 'user_id' (positive integer). This prevents the user from accessing the organization.

Edit the description/summary of a specific step in a template. The description supports HTML. Use this to add rich instructions, checklists, or converted document content to a step. When a user wants to convert a document to step instructions, read the document content yourself and write the HTML here. Only the description changes: this tool reads the step first and re-sends its existing title and assignees (members, guests and groups), which the API would otherwise clear on an update that omits them. To change who a step is assigned to, use add_assignees_to_step instead. REQUIRED: 'template…

Re-enable a disabled guest account. REQUIRED: 'email' (valid email).

Re-enable a disabled user account. REQUIRED: 'user_id' (positive integer).

Explains why a step in a running process is shown or hidden, from the record Tallyfy keeps each time it checks an automation rule for that process. REQUIRED: 'process_id' (32-character hex). OPTIONAL: 'task_id', one task in that process, which narrows the answer to that step. The rules come from the template version the process launched from, which can differ from the template as it is today; 'launched_from' names that version. For each rule it returns the latest recorded check: when it ran, whether it executed, each condition with the value the rule expects and whether it was met, and the ac…

Description is built at runtime.

Get templates (checklists) with full details including prerun fields, automated actions, linked tasks, and metadata. Returns 20 per page. Use page=2, page=3, etc. for more. meta.total_pages shows total page count. Optional: filter by folder name or folder ID.

Read a file that was uploaded to Tallyfy. Returns the file's metadata (filename, MIME type, size in bytes) and its bytes as base64 in content_base64. Use this whenever you need the contents of a file attached to a File Upload form field, a kickoff field, or a task comment. Get the asset_id from get_task, where a File Upload field's taskdata value carries it, or from a previous upload_asset response. Files over 10MB are NOT downloaded: you get the metadata plus content_omitted_reason saying why, and content_base64 is null. Partial content is never returned, so a non-null content_base64 is alway…

Get the options on a dropdown/radio/multiselect field, as {"id", "text"} objects. REQUIRED: 'template_id', 'step_id', and 'field_id'. The id is needed to WRITE a value: dropdown takes {"id","text"}, multiselect a list of {"id","text","selected":true}, radio the bare text. Options the API could not have issued (missing an id or a text) are OMITTED rather than given a made-up id, so an empty list means none were usable and NOT that the field has no options - do not feed an empty result back into update_dropdown_options, which would replace the real list.

Get a single group by its ID. REQUIRED: 'group_id'.

Get all groups in the organization. Use group IDs to filter processes via get_organization_runs(groups=<group_id>) or assign tasks. All parameters are optional.

Get a single guest's profile by email address. Returns name, contact info, last accessed time, and whether the guest is currently disabled. WHETHER A GUEST IS DISABLED: read the top-level 'is_disabled' boolean. It is always present and it is the answer. 'details.disabled_at' carries the timestamp when there is one. Do NOT read 'details.status' for this. It is a separate value that disable_guest and enable_guest never touch, and it is often empty. 'details.disabled_by' and 'details.reactivated_at' are history, not current state: each one survives the opposite operation, so a guest who was di…

Get all tasks assigned to a specific guest (external user). IDENTIFICATION: Provide guest_id or guest_email. CORRECT usage: - get_guest_tasks(guest_id="MITxZa1z2f5d81bb53f1da7c7fa95a2cfec5cbc2"): fastest, no lookup needed - get_guest_tasks(guest_email="guest@example.com"): resolves email to guest_id automatically WRONG usage (will fail): - get_guest_tasks(): NO! Must provide at least one identifier For org member tasks, use get_user_tasks() instead. For the current user's ACTIVE tasks, use get_my_tasks() (no identifier needed). IMPORTANT: Tallyfy has no "urgent" or "priority" field. No ta…

Get dropdown/radio/multiselect options for a kickoff (prerun) field. REQUIRED: 'template_id' and 'field_id'. Returns the options array for the specified kickoff field. Only works on fields with field_type dropdown, radio, or multiselect; returns an error for other field types. CORRECT usage: get_kickoff_dropdown_options(template_id="abc...", field_id="def...")

Get all kickoff/prerun fields for a template. REQUIRED: 'template_id'.

Get the currently authenticated user's profile data. No parameters required. USE THIS TOOL when user asks: - "Who am I?" - "What's my name?" - "Show my profile" - "What's my user ID?" - "What organization am I in?" Returns the authenticated user's full profile including numeric 'id', 'email', 'first_name', 'last_name', and organization details.

Get tasks assigned to the current user. USE THIS TOOL when user asks: - "What are my tasks?" - "Show me my tasks" - "What do I need to do?" - "What's assigned to me?" This tool returns task data including task IDs, run_ids (process IDs), titles, deadlines, and status. Use the returned data to answer follow-up questions about "those tasks" without making additional tool calls. IMPORTANT: Tallyfy has no urgency or priority field. No task ever carries status="overdue" or status="hasproblem"; those are query-side filter values only. A task's status is one of: not-started, in-progress, auto-skip…

Read this organization's saved memory: a curated markdown document of durable facts learned in past conversations (naming conventions, key templates, who does what, decisions already made). Useful before designing or building something for this org, because it records what is already true here. RETURNS: the document as markdown, or an honest empty answer when nothing has been saved yet. It is scoped to the authenticated organization only; there is no way to read another org's memory. Pair with update_org_context to keep it current. If the user asks what you know about their org, show them t…

Get organization details. No parameters required; the organization is determined from the authentication context. Returns the organization profile, including 'users_count'. IMPORTANT: 'users_count' IS AN ACTIVE-MEMBER COUNT, NOT TOTAL HEADCOUNT. It counts only members with a verified email, an approved membership, an accepted invite or a prior sign-in, and no disabled flag. EXCLUDED from 'users_count' but PRESENT in get_organization_users, which is exactly why the two numbers differ: - members invited who never accepted and never signed in (status 'invited') - disabled members (status 'disa…

Get all organization guests with full profile data. All parameters are optional. Use 'with_stats' (true/false) to include guest activity statistics. PAGINATION: Returns 20 results per page. Use page=2, page=3, etc. for more. meta.total_pages shows total page count.

Get all organization guests with minimal profile data for listing. Returns data with pagination metadata.

Get workflow processes (runs) in the organization. All parameters are optional. Call with no parameters to get all runs, or use filters to narrow results. FILTERS: status, archived, starred, checklist_id (template_id), tag, folder, groups, owners, run_type, me (bool) RUN STATUS VALUES: "active", "problem", "delayed", "complete", "improvement", "starred", "archived" ARCHIVED: archived="only" returns archived processes. status="archived" also works: this tool translates it to archived="only" for you. RUN TYPE VALUES: "procedure", "form", "document" FOLDER: Pass folder ID or folder name (name is…

Get organization members with full profile data. No required parameters. USE THIS TOOL when user asks: - "Who are the team members?" - "List all users" - "Show me organization members" - "Find user by name/email" (then search results for the user) Returns user data including numeric 'id', 'email', 'first_name', 'last_name'. Use the returned 'id' field when you need to call get_user_tasks(user_id=...). SCOPE: returns ALL members regardless of status (active, invited, and disabled), so meta.total is the FULL member roster, not an active-member count. Each record carries a 'status' of 'active'…

Get all organization members with minimal profile data for listing. Returns data with pagination metadata.

Get full details for a single process (run) by ID. REQUIRED: 'run_id'.

Get all process/run folders in the organization. Returns folders that contain active processes (folder_type='run'). Use returned folder IDs with get_organization_runs(folder=<folder_id>) to filter processes by folder. Results include nested child folders sorted by position. Optional: filter by name with 'q'.

Read one scheduled job with its run history. REQUIRED: 'job_id' (a whole number, from get_scheduled_jobs). Returns the job (status, schedule, the zone its times are read in, its next run where Tallyfy reports it) and its newest 20 runs, newest first, each with success, message and when it ran. A failed run's message says why. A one-time job whose run failed is left paused. A job the caller may not see answers not found, the same as a job that does not exist.

List the kinds of scheduled job this organization's Tallyfy offers, and the organization's time zone. A scheduled job runs on its own at a set time, once or on a repeat. launch-process starts a process from a template: schedule one with schedule_process_launch. create-task makes a one-off task and cannot be scheduled through these tools yet. Each kind lists the fields its data takes ('validations'). Give every time to schedule_process_launch in the organization's local time, the zone this tool reports. That tool works out how Tallyfy stores it.

List the organization's scheduled jobs: what each launches or creates, when it runs, and whether it is active, paused or completed. A member sees only the jobs they created and the launch jobs for templates they can launch; an admin sees all. Set mine=true for only the caller's own jobs. Each job says which zone its start_date and schedule.start_time are read in (times_are_read_in) and, where Tallyfy reports it, its next run in UTC and local time. For a launch job, data.checklist_id is the template and data.name the name each launched process gets. PAGINATION: 25 jobs per page. Use page=2, …

Get a standalone (one-off) task by ID, including any form fields (questions) on it and the answers submitted so far. REQUIRED: 'task_id'.

Read-only: analyze which automations affect when this step appears in the workflow. Inspects all template rules referencing the step as condition trigger OR action target. RETURN: {step_info: {id,title,position,summary}, dependencies: {incoming: [{step_id,step_title,condition_type,automation_id,description}], outgoing: [{step_id,step_title,action_type,automation_id,description}], field_dependencies: [{field_label,expected_value,condition_type,automation_id,description}], conditional_visibility: [{action_type:"show_step"|"hide_step",automation_id,description}], deadline_anchors: [{step_id,step…

Analyze when and how a step becomes visible based on all automations. REQUIRED: 'template_id' and 'step_id'.

Get the organization's tags. Use tags to filter processes via get_organization_runs(tag=<tag_id>). All parameters are optional. RETURNS EVERY TAG by default: the call reads every page of the API itself, so do not page through the result, and per_page does not limit it. If the response is an object with 'data' and '_truncated', the list was too large to return whole: narrow it with q=<substring>, or read past the cut with page=2, page=3 and so on. A page above 1 returns only that one page of per_page tags (page=2, per_page=100 is tags 101-200), so it repeats tags already shown; dedupe by id. If…

Get a single task from a process by ID, including any form fields (questions) on it and the answers submitted so far. REQUIRED: 'run_id' (32-char hex process ID) and 'task_id'.

Get all comments (threads) on a task. REQUIRED: 'task_id'. Optional: 'run_id' (32-char hex process ID), provide it if you have it to avoid an extra lookup. 'run_id' identifies the PROCESS the task belongs to, so it is a DIFFERENT id from 'task_id'. If you only have the task id, omit 'run_id' entirely rather than repeating the task id there. If run_id is omitted, it is resolved automatically from the task. Standalone (one-off) tasks have no run_id: omit it and their comments are read directly.

Get tasks for a specific process (workflow run). MANDATORY: You MUST provide either 'process_id', 'run_id', OR 'process_name'. Calling with empty parameters WILL FAIL. CORRECT usage examples: - get_tasks_for_process(process_id="abc123") - when you have the process/run ID - get_tasks_for_process(run_id="abc123") - alias for process_id (consistent with other task tools) - get_tasks_for_process(process_name="Hiring John Doe") - when you have the process name WRONG usage (will fail): - get_tasks_for_process() - NO! Missing required parameter - get_tasks_for_process(process_id=None) - NO! Must p…

Get a template (checklist) by its ID or name with full details. MANDATORY: You MUST provide either 'template_id' OR 'template_name'. Calling with empty parameters WILL FAIL. CORRECT usage examples: - get_template(template_id="a1b2c3d4e5f6789012345678901234ef") - 32-char hex ID from a previous result - get_template(template_name="Employee Onboarding") - when you know the template name WRONG usage (will fail): - get_template() - NO! Missing required parameter - get_template(template_id="", template_name="") - NO! Must provide a value for one If you don't have a template_id or name, use searc…

Get all template/blueprint folders in the organization. Returns folders that contain templates (folder_type='checklist'). Use returned folder IDs with launch_process(folders=[<folder_id>]) to launch into a folder. Results include nested child folders sorted by position. Optional: filter by name with 'q'.

Get all steps for a template in order. USE THIS instead of get_template when the user asks about steps. MANDATORY: 'template_id' is required. USE THIS TOOL when the user asks: - "What are the steps in [template]?" - "List the steps of [template]" - "Show me the steps for [template]" - Any question about a template's steps or structure - Finding a step's ID before editing or assigning it WORKFLOW: If you don't have the template_id yet: 1. Call search_for_templates(query="<template name>") to get the template_id 2. Then call get_template_steps(template_id="<id>") CORRECT usage: - get_templat…

Get a single user by their numeric ID. REQUIRED: 'user_id' (positive integer).

Get all tasks assigned to a specific organization member (not the current user). IDENTIFICATION: Provide one of user_id, user_name, or user_email. CORRECT usage: - get_user_tasks(user_id=12345): fastest, no lookup needed - get_user_tasks(user_name="Zurly Venom"): resolves name to ID automatically - get_user_tasks(user_email="zurly@example.com"): resolves email to ID automatically WRONG usage (will fail): - get_user_tasks(): NO! Must provide at least one identifier GUEST USERS: This tool is for org members only. For guest tasks, use get_guest_tasks(guest_email="...") or get_guest_tasks(gues…

Invite a new member to the organization. MANDATORY - ALL THREE required: 1. 'email' - Valid email address 2. 'first_name' - User's first name 3. 'last_name' - User's last name CORRECT usage: - invite_user_to_organization(email="john@example.com", first_name="John", last_name="Doe") - invite_user_to_organization(email="jane@example.com", first_name="Jane", last_name="Smith", role="standard") WRONG usage (will fail): - invite_user_to_organization(email="john@example.com") - NO! Missing first_name and last_name - invite_user_to_organization(first_name="John", last_name="Doe") - NO! Missing ema…

Launch a new workflow process (run) from a template. REQUIRED: 'template_id' and 'name'. Name it after the template plus the real-world thing it tracks. Generate it; ask only if they want to pick. Launch ONE process per real-world thing (per hire, per order). At volume the fix is less LAUNCHING WORK, not fewer processes: repeat this call once per row of their list, instead of them launching each one by hand. PEOPLE: 'users' takes member IDs, 'guests' takes EMAILS - never swap them, and pass both in ONE call. A guest cannot be a member of a process, so 'guests' assigns them to its TASKS inste…

Move form field between steps with position control. REQUIRED: 'template_id', 'from_step', 'field_id', and 'to_step'. Optional: 'position' (1-BASED integer between 1 and 9999, where the first field is position 1, not 0; defaults to 1).

Pause a scheduled job so it does not run until it is resumed. REQUIRED: 'job_id'. Only the status changes; the schedule and what the job launches stay as they are. resume_scheduled_job starts it again. A completed job has finished and cannot be paused. Returns the job as Tallyfy stored it, with status paused and no next run.

Reactivate an archived process (run) to make it active again. REQUIRED: 'run_id'.

Remove an object from a folder using the folder-object relation ID. REQUIRED: 'folder_object_id', a positive INTEGER (e.g. 12345, or "12345" exactly as add_object_to_folder returns it), NOT a 32-char hex ID. This is the id of the folder-membership row itself, not the id of the process inside the folder. It is the 'id' that add_object_to_folder(object_type='run') returns. No tool can look it up afterwards, so if that id was not kept, say so rather than guessing. CORRECT: remove_object_from_folder(folder_object_id=12345) WRONG: remove_object_from_folder(folder_object_id="7c9e6679742540de…

Reopen a completed kickoff form, which UN-COMPLETES the process: it takes an already-finished run back out of its finished state, not just 'allow edits' on it. That can shift SLA/deadline calculations and re-trigger completion-based automations. REQUIRED: 'run_id' (32-char hex process ID).

Reopen a previously completed standalone (one-off) task. REQUIRED: 'task_id' and 'reason' (string explanation for reopening). Use THIS tool (not reopen_task) for a task created via create_standalone_task: one that has no run_id you already know. Same dispatch behavior as complete_standalone_task: it looks the task up first and routes correctly whether or not it turns out to be linked to a process or a hidden container run. ⚠️ MANDATORY `reason` PARAMETER: - The `reason` parameter is REQUIRED (not optional). Empty/whitespace-only strings raise ToolError. - It mirrors the native Tallyfy UI…

Reopen a previously completed task. REQUIRED: 'run_id' (32-char hex process ID), 'task_id', and 'reason' (string explanation for reopening). ⚠️ MANDATORY `reason` PARAMETER: - The `reason` parameter is REQUIRED (not optional). Empty/whitespace-only strings raise ToolError. - It mirrors the native Tallyfy UI, which requires a reason before reopening. - The reason is automatically posted as a comment on the task for audit trail purposes, visible to all task participants and persisted permanently in the run history. - Length: keep it concise (1-2 sentences, ideally under 500 characters).…

Reorder form fields in a step. REQUIRED: 'template_id', 'step_id', and 'field_order'. Pass 'field_order' as EITHER a list of field IDs in the desired order (positions assigned 1, 2, 3, ... by list order), OR a list of {capture_id, position} objects when you need explicit non-sequential positions.

Reorder kickoff (prerun) fields on a template. REQUIRED: 'template_id' and 'field_order' (list of field IDs in desired order). The API assigns position sequentially based on array order: first ID gets position 1, second gets position 2, etc. Fields not included in field_order are appended at the end in their original relative order. CORRECT usage: reorder_kickoff_fields(template_id="abc...", field_order=["field_id_3", "field_id_1", "field_id_2"])

Move a step to a new position in a template. REQUIRED: 'template_id', 'step_id', and 'position' (1-based integer >= 1; the first step is position 1, not 0).

Report an issue on a task. REQUIRED: 'task_id' and 'content' (issue description). Optional: 'run_id' (pass if available). Creates a comment with 'problem' label.

Resolve a specific issue on a task. REQUIRED: 'task_id' and 'thread_id' (the issue comment ID returned by report_task_issue). Optional: 'run_id' (pass if available).

Resume a paused scheduled job. REQUIRED: 'job_id'. A repeating job picks up at its next run after now; runs it missed while paused are skipped, not made up. A one-time job whose time has passed cannot be resumed: schedule a new one with schedule_process_launch, then delete this one. A completed job has finished and cannot be resumed. Returns the job as Tallyfy stored it, with its next run where Tallyfy reports it.

Schedule a template to launch a process on its own, once or on a repeat. REQUIRED: template_id, process_name, repeat, start_date, time. Confirm the schedule with the user before calling it. WHEN, in the organization's LOCAL time (get_scheduled_job_types gives the zone). Do not convert to UTC: start_date: day of the first run, YYYY-MM-DD. The first run must still be ahead. time: HH:MM, 24 hour. repeat: once, hourly, daily, weekly, monthly or yearly. weekly runs on start_date's weekday, or on days_of_week (1 Monday to 7 Sunday). monthly runs on start_date's day of the month; year…

Search across multiple entity types in one request. Returns results grouped by type. MANDATORY: You MUST provide a 'query' parameter. Calling with empty/missing query WILL FAIL. Searches blueprints, processes, tasks, and snippets by default. Use the 'types' parameter to narrow down. Valid types: blueprint, process, task, snippet, capture, step. PAGINATION: Returns 20 items per page per entity type by default. Use page=2, page=3 for more results, or per_page to change page size (max 100). CORRECT usage examples: - search_all(query="onboarding") - search everything for "onboarding" - search_…

Search for workflow processes (runs) in the organization by keyword. MANDATORY: You MUST provide a 'query' parameter. Calling with empty/missing query WILL FAIL. CORRECT usage examples: - search_for_processes(query="onboarding") - search for onboarding processes - search_for_processes(query="John Doe") - search for processes related to John Doe - search_for_processes(query="Q4 report") - search for Q4 report processes WRONG usage (will fail): - search_for_processes() - NO! Missing required query parameter - search_for_processes(query="") - NO! Empty query not allowed Extract search terms f…

Search for text snippets (stored text templates) in the organization by keyword. MANDATORY: You MUST provide a 'query' parameter. Calling with empty/missing query WILL FAIL. CORRECT usage examples: - search_for_snippets(query="welcome email") - search for welcome email snippets - search_for_snippets(query="disclaimer") - search for disclaimer snippets WRONG usage (will fail): - search_for_snippets() - NO! Missing required query parameter - search_for_snippets(query="") - NO! Empty query not allowed Extract search terms from user's request. If user says "find the thank you snippet", use que…

Search for tasks in the organization by keyword. MANDATORY: You MUST provide a 'query' parameter. Calling with empty/missing query WILL FAIL. CORRECT usage examples: - search_for_tasks(query="urgent") - search for urgent tasks - search_for_tasks(query="review document") - search for document review tasks - search_for_tasks(query="approval") - search for approval-related tasks WRONG usage (will fail): - search_for_tasks() - NO! Missing required query parameter - search_for_tasks(query="") - NO! Empty query not allowed Extract search terms from user's request. If user says "find my tasks abo…

Search for workflow templates (blueprints) in the organization by keyword. MANDATORY: You MUST provide a 'query' parameter. Calling with empty/missing query WILL FAIL. CORRECT usage examples: - search_for_templates(query="onboarding") - search for onboarding templates - search_for_templates(query="HR") - search for HR-related templates - search_for_templates(query="approval workflow") - search for approval templates WRONG usage (will fail): - search_for_templates() - NO! Missing required query parameter - search_for_templates(query="") - NO! Empty query not allowed Extract search terms fro…

Search Tallyfy's official product documentation and return the top matching pages. Use this when the user asks HOW Tallyfy works or how to do something in the product: features, settings, limits, integrations, billing, troubleshooting. Answer from what it returns and link the page, instead of guessing product behavior from memory. RETURNS: up to 5 results as {title, snippet, url, score}, plus 'total'. score is relevance from 0 to 1; results below about 0.5 are weak matches, so treat an all-low-score page of results as the docs not covering the topic. Snippets are plain text with the matched …

Read-only: prioritized consolidation suggestions for a template's automation rules. `suggestion_type` (lowercase, in `type` field): - `orphaned_rule` (high): a condition or a then-action references a step, form field (Capture), or kickoff field (Prerun) that is not in the template. Includes `orphaned_step_ids`. Recommended: review; do NOT auto-delete, a rule may still hold valid actions. - `exact_duplicate` (high): IDENTICAL conditions AND actions across rules. Recommended: keep one, delete the rest. - `conflict` (high): same trigger, contradictory `action_verb`s on the same target (show/hide…

Retrieve step details with existing form fields to recommend additional fields. Returns the step's title, summary, type, and existing form fields (captures), plus the template title for context. Use this data to suggest relevant form fields by considering: - The step's purpose (inferred from title and summary) - What fields already exist (avoid duplicates) - Common patterns: approval steps need decision dropdowns, contact steps need text fields for email/phone, document steps need file uploads, financial steps need amount fields - Supported field types: text, textarea, date, dropdown, mult…

Retrieve template data with existing kickoff fields and step context to recommend new kickoff fields. Returns the template title, summary, existing prerun/kickoff fields, and step titles/summaries. Use this data to suggest kickoff fields that would help initialize the workflow by considering: - What information the steps will need (client names, project details, dates, budgets) - What existing kickoff fields already capture (avoid duplicates) - The template's domain and purpose (inferred from title, summary, and step content) - Field types: text, textarea, date, dropdown, multiselect, radio,…

Retrieve step details with template context to recommend an appropriate deadline. Returns the step's title, summary, position in the workflow, current deadline (if any), assignees, and the total number of steps in the template. Use this data to suggest a reasonable deadline by considering: - Step complexity (review/approve steps are quick; document creation takes longer) - Position in workflow (early steps may need faster turnaround) - Dependencies and assignee count - Whether the step has form fields that require data gathering DEADLINE SHAPE: all four keys travel together. api-v2 marks va…

Assign a user-defined tag to a running process. REQUIRED: 'run_id' and 'tag_id'. Optional 'tag_type': 'private' (default, every tag get_tags returns) or 'public' (only for a public tag id). Multiple tags per process are allowed. Call this tool repeatedly with the same run_id and different tag_ids to apply more than one. Re-tagging with an already-applied tag_id does NOT create a duplicate tag, but it is not a full no-op: it re-fires the tag event and appends an audit-trail entry, so avoid redundant calls. Tags are used for filtering (search_for_processes), grouping in dashboards, and organizin…

Assign a tag to a template. REQUIRED: 'template_id' and 'tag_id'. Optional 'tag_type': 'private' (default, every tag get_tags returns) or 'public' (only for a public tag id). ACTIVE TEMPLATES ONLY: an archived template cannot be tagged. Tallyfy resolves the subject with a lookup that skips archived (soft-deleted) templates, so the call fails with the validation error 'Subject not found'. That is the identical message a wrong or unknown template_id produces, so read it as 'archived OR unknown', never as proof the template does not exist. get_template does NOT settle it: that read skips archived…

READ-ONLY FALLBACK. Issues a GET against any Tallyfy REST API endpoint when no specific tool fits. This tool cannot modify anything; use tallyfy_api_write for that. Prefer a specific tool (search_*, get_*) whenever one matches. Only reach for this after confirming none does. AVAILABILITY: a server-side setting, OFF in Tallyfy's hosted service for every account, and it cannot be turned on for one account. A refusal is FINAL: nothing was sent or changed, and retrying cannot help. On a self-hosted server, the operator of that server controls it. Prefer a first-class tool. If none fits, say dire…

WRITE FALLBACK. Issues a POST, PUT, PATCH or DELETE against any Tallyfy REST API endpoint when no specific tool fits. This tool CHANGES OR DELETES DATA and is marked destructive, so each call is confirmed with the user. To read, use tallyfy_api_read. A specific tool (create_*, update_*, delete_*) is the better fit whenever one matches. The body argument is raw JSON for the endpoint; shape it per the Tallyfy API docs. Every call here is audit-logged. AVAILABILITY: a server-side setting, OFF in Tallyfy's hosted service for every account, and it cannot be turned on for one account. A refusal is…

Test a template BEFORE anyone runs it. Walks every path through the template internally and reports PROBLEMS, not paths: a step no answer can ever reach, an automation that can never fire, two automations fighting over one step, a visible step with nobody assigned, a path where the process gets stuck, an automation pointing at something deleted, a deadline counted from a step that may not happen, a condition waiting for a dropdown answer that no longer exists, and a start date that is set but ignored. USE THIS when someone asks whether a template works, why a step never appears, why nobody was…

Answer 'what happens if...' for one template WITHOUT running it. Give the answers you care about and it reports which steps appear, which stay hidden, who is assigned, which automations fire, and any problems on those answers. USE THIS for a specific question such as what happens when a request is declined; use test_template for a whole-template health check. REQUIRED: 'template_id' (32-character hex) and 'answers'. 'answers' is an OBJECT keyed by the FIELD LABEL exactly as a person sees it, for example {"Nominee decision": "Declined"}. A field id works too. Matching ignores case. An unknown l…

Remove a tag from a running process. REQUIRED: 'run_id' and 'tag_id'.

Remove a tag from a template. REQUIRED: 'tag_id' and 'template_id'.

Modify automation conditions and actions. THE PUT REPLACES conditions and actions WHOLESALE. Read the rule with analyze_template_automations first and send back EVERY condition and action you want to keep: a shorter list force-deletes the rest, HTTP 200, no warning. Omitting 'conditions' or 'actions' is a 422. REQUIRED (all three): 'template_id', 'automation_id', 'automation_data' (dict). Use "actions" (NOT "then_actions"). Use "alias" (NOT "automated_alias"). Use "step"/"field"/"kickoff" for conditionable_type (auto-resolved). STEP operations: completed, reopened, approved, rejected,…

Replace the options list on a dropdown/radio/multiselect form field. REQUIRED: 'template_id', 'step_id', 'field_id', and 'options' (list). ACCEPTED `options` FORMATS (pass EITHER; the tool normalizes both): Format A - STRING ARRAY (simplest, recommended for new options): options=["High", "Medium", "Low"] The tool auto-converts each string to {id: <sequential>, text: <string>}. IDs are assigned 1, 2, 3, ... in input order. Format B - DICT ARRAY with explicit ids and text: options=[ {"id": 1, "text": "High"}, {"id": 2, "text": "Medium"}, {"id": 3, "text"…

Update a folder's name or parent. REQUIRED: 'folder_id'. Plus at least one optional field.

Update form field properties, validation, or options on an existing form field. REQUIRED: 'template_id', 'step_id', 'field_id', and 'field_data' (dict). UPDATABLE vs IMMUTABLE PROPERTIES: UPDATABLE: - `label` human-readable name - `field_type` the field's type. api-v2 changes it in place and reconciles existing rules; do NOT delete then recreate (that hard-deletes every collected value). Changing TO dropdown/radio/multiselect also needs `options`; changing TO table also needs `columns`. - `guidance` help/instruction text shown under the field - `re…

Update a group's name, description, or members. REQUIRED: 'group_id'. Plus at least one optional field to update.

Set which organization members a guest is associated with. REQUIRED: 'email' (the guest to update) and 'associated_members' (list of numeric member user IDs, pass [] to clear). 'associated_members' REPLACES the whole list, it does not append. THIS TOOL CANNOT EDIT A GUEST'S PROFILE. The update-guest endpoint accepts only the guest's email (to identify them) and associated_members; the API validates nothing else, so first_name, last_name, phone and company_name CANNOT be changed here: a request carrying them is accepted with a success status and those values are silently discarded. Do not tel…

Update a kickoff (prerun) field on a template. REQUIRED: 'template_id', 'field_id', and 'field_data' (dict). UPDATABLE PROPERTIES: label, guidance, required (bool), position, options (dropdown/radio/multiselect), columns (table), collect_time, use_wysiwyg_editor, field_validation, default_value, default_value_enabled, prefix, suffix, settings. IMMUTABLE: id, alias - cannot be changed. `field_type` CAN be changed in place (send the new type plus any options/columns it needs); do NOT delete and recreate, which drops collected data. AUTO-FILLED: This tool fetches the current field and m…

Save this organization's memory: replace the whole curated markdown document of durable facts (naming conventions, key templates, who does what, decisions made). FULL-REWRITE SEMANTICS: what you send REPLACES the document. Read get_org_context first, merge the new fact in, and send the complete updated document. The previous version is retained server-side so an administrator can restore it. VISIBLE TO THE USER: the user can read the saved document at any time with get_org_context and correct it. WHAT BELONGS HERE: stable, reusable facts (the org calls customers "members"; onboarding runs t…

Update a process name, summary, or starred status. Only those properties change: this tool reads the process first and re-sends its existing members and groups, which the API would otherwise detach from the running process on an update that omits them. REQUIRED: 'run_id' plus at least one of: 'name', 'summary', or 'starred'.

Update a standalone (one-off) task that was created via create_standalone_task. Use THIS tool (not update_task) when the task has no run_id or was created as a one-off task. Use update_task instead when the task belongs to a workflow process run. REQUIRED: 'task_id' plus at least ONE field to update. Field variables in HTML: read tallyfy://variable-markup.FORM FIELD VALUES ('taskdata'): dict keyed by the form field's id. Send the value ITSELF: a {"value":...} wrapper is REJECTED by most types and stored VERBATIM by email (silent corruption). Never send one. text -> scalar e.g. "Acme…

Edit an EXISTING step in place, keeping its id, automations, form fields and history. To RENAME a step, pass 'title'. Also use this to change its deadline, start date, type or instructions. Never delete_step then add_step_to_template to edit: that mints a NEW id and orphans every automation pointing at the old one. REQUIRED: 'template_id', 'step_id', and 'step_data', a dict of ONLY the fields to change. A field you omit is left alone; pass an empty list to CLEAR one. An unknown key is refused with the full list of valid ones. step_data keys: - 'title': the step name. This is the rename. …

Update a tag's title or color. REQUIRED: 'tag_id'. Plus at least one optional field. 'color' must be EXACTLY 7 characters as #RRGGBB (e.g. '#FF5733'); shorthand, alpha and named colors are rejected.

Update task properties including deadline, assignees, title, or form field values. REQUIRED: 'run_id' (32-char hex process ID) and 'task_id'. Plus at least ONE optional field to update. FORM FIELD VALUES ('taskdata'): dict keyed by the form field's id. Send the value ITSELF: a {"value":...} wrapper is REJECTED by most types and stored VERBATIM by email (silent corruption). Never send one. text -> scalar e.g. "Acme Corp" · textarea -> string only (12345 -> 422) date -> "2026-03-01 09:00:00" (epoch int -> 422) · email -> "a@b.com" file -> LIST of objects, never a scalar; …

Update an existing comment on a task. REQUIRED: 'task_id', 'comment_id', and 'content' (new text). Optional: 'run_id' (pass if available), 'label', 'state', 'sent_to' (list of numeric user IDs to @mention, rendered into the body as @[<user_id>] markup, which is what notifies them; you can also write @[20059] / @20059 / @alice@acme.com / @"Alice Smith" / @alice directly in 'content' and it is normalised for you).

Update a template's metadata (title, summary, settings). REQUIRED: 'template_id' plus at least one property to update. Updatable fields: title, summary, guidance, icon, alias, webhook, is_public, is_featured, auto_naming, default_process_name_format, folderize_process, tag_process, allow_launcher_change_name, is_pinned, default_folder, kickoff_title, kickoff_description. LAUNCH NAMING. A template created through this connector starts with auto_naming OFF and default_process_name_format EMPTY, because those are the column defaults and create_template sends neither. So a template you BUILT he…

Upload a file to a Tallyfy form field. Give it the file as base64 in content_base64 plus a filename, and say where it goes. There are three shapes. (1) A KICKOFF field on a template: uploaded_from='ko_field', subject_type='Template', subject_id=<template id>. (2) A form field on a task in a running process: uploaded_from=<field id>, subject_type='Process', subject_id=<process id>, and BOTH step_id (the step that owns the field) and checklist_id (the template the process was launched from) are required. (3) A form field on a STANDALONE task, the one-off kind made by create_standalone_task: uplo…

Validate a DRAFT Tallyfy template mapping before building it. USE THIS after you have turned a flowchart / SOP / process diagram into a draft template structure, and BEFORE you call create_template + add_step_to_template + add_form_field_to_step + create_automation_rule. It checks every step_type, form field_type, deadline, and automation (condition operations + action types/verbs) against Tallyfy's allowed values, and confirms every automation target / condition reference resolves to a step/field defined in the same mapping. Returns a precise error list so you fix the mapping in one pass ins…