Tallyfy Workflow Automation

Ask the user to drag-rank a list of options into a preferred order. Use when the agent has a candidate list (templates, tasks, options) whose ordering depends on the user's intent and a free-text answer would be lossy. RESPONSE FORMAT: When the user submits, the host forwards their ranked order back as a synthetic turn shaped like [Ranking answer (interaction_id=...) interaction_type=ranking] order=[id1, id2, id3]. The order reflects the user's drag arrangement; the items themselves are unchanged. If the user dismisses the form, a cancel_interaction frame fires and the agent receives [User cancelled prior interaction (interaction_id=...)].

ask_user_to_rank

Retrieve complete template data for a comprehensive health assessment. Returns the full template including metadata, steps, automation rules, and kickoff fields. Use this data to evaluate template health across these dimensions: - Metadata quality: Does it have a clear title, summary, and guidance? - Step clarity: Do steps have descriptive titles and summaries? Are any too vague? - Form completeness: Do steps that need data collection have appropriate form fields? - Automation efficiency: Are automation rules well-structured? Any conflicts or redundancies? - Deadline configuration: Do time-sensitive steps have reasonable deadlines? - Workflow structure: Is the step count manageable? Is the flow logical? Provide an overall health rating (excellent/good/fair/poor/critical) with specific recommendations. RETURNS: full template payload — top-level keys include `id`, `title`, `summary`, `steps[]`, `automated_actions[]`, `prerun[]` (kickoff fields), and metadata. Synthesize this into a `health_rating` (one of: excellent, good, fair, poor, critical) plus a `recommendations` list (string array of specific, actionable improvements). The tool returns RAW data — the LLM is responsible for the rating + recommendations synthesis. REQUIRED: 'template_id' (32-character hex string). Never call this without the template_id parameter.

assess_template_health

Change a user's role in the organization. REQUIRED: 'user_id' (positive integer) and 'role' ('light', 'standard', or 'admin'). Never call this without both parameters.

change_user_role

Clone (duplicate) a step within a template. REQUIRED: 'template_id' (32-char hex) and 'step_id' (32-char hex). Creates an exact copy of the step including form fields and assignees. Never call this without both parameters.

clone_step

Clone (duplicate) a template with a new name. REQUIRED: 'template_id' (32-char hex) and 'new_name' (string). The clone copies steps, form fields and automation rules. Permissions are handled by the API's own clone semantics and are NOT controllable from here — there is no parameter to opt in or out. CORRECT usage: clone_template(template_id="a1b2c3d4e5f6789012345678901234ef", new_name="Employee Onboarding v2") Never call this without both required parameters.

clone_template

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

complete_kickoff_form

Mark a task as complete. REQUIRED: 'run_id' (32-char hex process ID) and 'task_id' (32-char hex). 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) task_type="approval" -> MUST pass is_approved=True or is_approved=False task_type="expiring" -> do NOT pass is_approved (completing acknowledges it) task_type="expiring_email" -> do NOT pass is_approved (completing acknowledges it) task_type="email" -> do NOT pass is_approved (regular completion) is_approved is honored ONLY for approval tasks. On task/email it is ignored. On expiring or expiring_email it is NOT ignored: is_approved=False would record the task as EXPIRED instead of ACKNOWLEDGED, so this tool refuses is_approved=False on an expiring task. There is no way to mark a task expired through this tool. CORRECT usage: complete_task(run_id="...", task_id="...") # regular or expiring task complete_task(run_id="...", task_id="...", is_approved=True) # approve an approval task complete_task(run_id="...", task_id="...", is_approved=False) # reject an approval task Get run_id, task_id, and task_type from get_tasks_for_process() or get_my_tasks(). Never call this without both required parameters.

complete_task

Create conditional automation (if-then rules) for workflow templates. REQUIRED: 'template_id' (32-char hex) + 'automation_data' (dict with `conditions`+`actions`). COMPATIBILITY - action_type CONSTRAINS action_verb, they are NOT independent: visibility -> show | hide deadline -> deadline status -> reopen webhook -> emit_webhook assignment -> assign | assign_only | unassign | clear_assignees `reopen` NEVER pairs with `visibility`. Single-verb types may omit action_verb. conditionable_type: step | field | kickoff (auto-resolved) Step ops: completed, reopened, approved, rejected, acknowledged, expired, not_assigned Field/kickoff ops: contains, not_contains, equals, not_equals, equals_any, greater_than, less_than, is_empty, is_not_empty EVERY condition needs a `statement` key (null for step ops). AND/OR goes on EACH condition as `logic`:"and"|"or". No top-level condition_logic exists. EXAMPLE (ids are 32-char hex, no hyphens) - SHOW a step when a kickoff field = "Yes" (to hide it: action_verb "hide"): {"alias":"Show legal","conditions":[{"conditionable_id":"<ko_field_id>","conditionable_type":"kickoff","operation":"equals","statement":"Yes","logic":"and"}],"actions":[{"action_type":"visibility","action_verb":"show","target_step_id":"<step_id>"}]} Same envelope for other actions, swapping the "actions" entry: deadline: {..,"action_type":"deadline","deadline":{"value":3,"unit":"days","option":"from"}} assign: {..,"action_type":"assignment","action_verb":"assign","assignees":{"users":[12345]}} Every action needs `target_step_id`. deadline needs ALL of value/unit/option (unit minutes|hours|days|weeks|months, option before|from). webhook needs webhook_url+alias_name. Use "actions" (NOT "then_actions"). Tallyfy requires "alias" (a short rule name, NOT "automated_alias"); if you omit it this tool fills one in.

create_automation_rule

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=...)), you MUST create it with folder_type="run". A default 'checklist' folder will reject processes. - To file TEMPLATES into it (add_object_to_folder(object_type="template")), use the default folder_type="checklist". CORRECT usage: create_folder(name="Q1 2026", folder_type="run") # holds processes create_folder(name="HR Templates") # holds templates create_folder(name="Payroll", folder_type="run", parent_id="7c9e6679742540de944be07fc1f90ae7") Never call this without name.

create_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", members=[20059, 20033]) Never call this without both name and description.

create_group

Create a new guest (external collaborator) in the organization. REQUIRED: 'email' (valid email), 'first_name', 'last_name'. Optional: 'phone_1' (primary phone, max 20 chars), 'phone_2' (secondary phone, max 20 chars), 'company_name' (max 200 chars). NOTE the phone parameter names: the API stores two numbered phone fields, 'phone_1' and 'phone_2'. There is no plain 'phone' field — a value sent as 'phone' is silently discarded and the guest is created without it. CORRECT usage: create_guest(email="[email protected]", first_name="Alice", last_name="Smith") create_guest(email="[email protected]", first_name="Bob", last_name="Jones", phone_1="+1 314 555 0100", company_name="Vendor Inc") Never call this without the three required parameters.

create_guest

Create a standalone (one-off) task with explicit structured fields. NOTE: Tallyfy internally creates a lightweight process container for every standalone task — this is expected platform behaviour and the task will still appear as a one-off task (is_oneoff_task: true). REQUIRED FIELDS: title, deadline, and at least one assignee. DEADLINE: Accepts natural language — e.g. "April 12 2026 at 3pm", "next Monday at noon", "tomorrow at 5pm". Resolved to UTC using the org timezone automatically. TASK TYPE: Accepted values: - "task" (default) — standard task - "approval" — approval/reject task - "expiring" — expiring task - "email" — email draft task - "expiring_email" — auto-send email task ASSIGNEES: Provide one or more of: - user_names: member full names (e.g. ["John Doe"]) - user_emails: member email addresses - guest_emails: guest email addresses - group_names: group names CORRECT usage: - create_standalone_task(title="Review budget", deadline="tomorrow at 3pm", user_emails=["[email protected]"]) - create_standalone_task(title="QA test", task_type="approval", deadline="April 12 2026", user_names=["Jane Smith"], description="Routine QA validation") If the user doesn't specify a deadline or assignee, ASK them before calling the tool.

create_standalone_task

Create a new tag in the organization. REQUIRED: 'title' (tag name). Optional: 'color' (hex color code like '#FF5733'). Never call this without title.

create_tag

Create a new template (checklist/blueprint). This is the first step when building a workflow from a user's description, uploaded document, or image — create the template shell here, then call add_step_to_template for each step, add_form_field_to_step for form fields, add_kickoff_field for pre-launch fields, and create_automation_rule for if-then logic. REQUIRED: 'title' (template name). Optional: 'type' ('procedure' for multi-step workflows, 'form' for data collection, 'document' for reference docs), 'summary', 'guidance', 'starred'. Never call this without title.

create_template

Remove an automation rule from a workflow template. REQUIRED: 'template_id' (32-char hex) and 'automation_id' (32-char hex). Never call this without both parameters.

delete_automation_rule

Delete a folder permanently. REQUIRED: 'folder_id'. Contents are NOT deleted — processes/templates are moved out first. Never call this without folder_id.

delete_folder

Delete a form field from a step. REQUIRED: 'template_id' (32-char hex), 'step_id' (32-char hex), and 'field_id' (32-char hex). NOTE: if the field is referenced by an automation rule (visibility condition) in another step, deletion fails with a 403 error; remove the automation rule first. Never call this without all three parameters.

delete_form_field

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

delete_group

Delete a kickoff (prerun) field from a template. REQUIRED: 'template_id' (32-char hex) and 'field_id' (32-char hex). WARNING: Deleting a kickoff field removes it permanently and drops all collected data for that field across existing process runs. This cannot be undone. NOTE: If the field is used in an automation rule (visibility condition), the deletion will fail with a 403 error; remove the automation rule first. Never call this without both parameters.

delete_kickoff_field

Delete a step from a template PERMANENTLY. REQUIRED: 'template_id' (32-char hex) and 'step_id' (32-char hex). 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 → "Cannot delete this step because other steps have deadlines that depend on it." So you MUST clear the dependents FIRST to preserve or retarget them: use `get_step_dependencies` / `analyze_template_automations` to find what points at this step, then `update_automation_rule` (or `delete_automation_rule`) and re-anchor any dependent deadlines. Only then will the delete succeed. Never call this without both parameters.

delete_step

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

delete_tag

Delete a comment from a task. REQUIRED: 'task_id' (32-char hex) and 'comment_id'. Optional: 'run_id' (pass if available). This action cannot be undone. Never call this without both required parameters.

delete_task_comment

ARCHIVE a template. REQUIRED: 'template_id' (32-char hex). This is a RECOVERABLE soft delete, NOT a permanent one. The template is archived (hidden from default template lists) and its steps, form fields and automation rules are preserved. Tallyfy exposes a restore endpoint, so an archived template can be brought back — reassure the user rather than warning them the action is irreversible. References to the template from folders and similar relations ARE removed, and the response lists what was detached under `deleted_references`. Permanently purging a template is a separate admin-only API operation that this tool does not perform, and it still requires the template to be archived first. Never call this without template_id.

delete_template

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

disable_guest

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

disable_user

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_id' (32-char hex), 'step_id' (32-char hex), and 'description' (new text, HTML allowed). Never call this without all three parameters.

edit_description_on_step

Re-enable a disabled guest account. REQUIRED: 'email' (valid email). Never call this without email.

enable_guest

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

enable_user

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.

get_all_templates

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_me

Get the options on a dropdown/radio/multiselect field, as {"id", "text"} objects. REQUIRED: 'template_id' (32-char hex), 'step_id' (32-char hex), and 'field_id' (32-char hex). Never call this without all three parameters. 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_dropdown_options

Get a single group by its ID. REQUIRED: 'group_id'. Never call this without group_id.

get_group

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_groups

Get a single guest's profile by email address. Returns guest profile data including name, contact info, last accessed time, and status. NOTE: This returns the guest's profile only, not their tasks. To get tasks assigned to a guest, use get_guest_tasks(guest_email="...") or get_guest_tasks(guest_id="...") with the guest_id from this response. CORRECT usage: - get_guest(email="[email protected]")

get_guest

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="[email protected]") — 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 tasks, use get_my_tasks() (no identifier needed). IMPORTANT: Tallyfy has no "urgent" or "priority" field. For urgent tasks, call with no status filter and look for status="overdue" or status="hasproblem" in results. PAGINATION: Returns 20 tasks per page. Use page=2, page=3, etc. for more. meta.total_pages shows total page count.

get_guest_tasks

Get dropdown/radio/multiselect options for a kickoff (prerun) field. REQUIRED: 'template_id' (32-char hex) and 'field_id' (32-char hex). 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...") Never call this without both parameters.

get_kickoff_dropdown_options

Get all kickoff/prerun fields for a template. REQUIRED: 'template_id' (32-character hex string). Never call this without the template_id parameter.

get_kickoff_fields

Get tasks assigned to the current user. No parameters required. 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. For "urgent" tasks, look for status="overdue" or status="hasproblem" in the returned results. NOTE: This tool does NOT support status filtering. It returns all tasks for the current user. To filter by status, retrieve all tasks and filter the results client-side. PAGINATION: Returns 20 tasks per page. Use page=2, page=3, etc. to retrieve subsequent pages. meta.total_pages shows how many pages exist. meta.total shows the real count.

get_my_tasks

Get organization details. No parameters required — organization is determined from authentication context.

get_organization

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_organization_guests