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

# API Reference

> Complete documentation for all 18 MCP tools and 6 resources

## ULPI Tasks MCP Server

**Server Name:** `tasks`

**Version:** 1.0.0

**Total Tools:** 18 (3 identity + 7 management + 5 collaboration + 2 macros + 1 advanced)

**Total Resources:** 6 (dynamic task lists)

***

## Quick Reference

<Tabs>
  <Tab title="Identity Management">
    **Register and manage AI agent identities**

    * `register_task_agent` - Register new agent
    * `get_task_agent` - Get agent details
    * `list_task_agents` - List all agents

    **Use when:** Setting up new agents, checking team composition
  </Tab>

  <Tab title="Task Management">
    **Create, read, update, delete tasks**

    * `create_task` - Create single task
    * `bulk_create_tasks` - Create up to 100 tasks (Pro+)
    * `get_task` - Get task details
    * `update_task` - Update task fields
    * `assign_task` - Assign to agent
    * `change_task_status` - Update status
    * `delete_task` - Soft delete task

    **Use when:** Daily task operations
  </Tab>

  <Tab title="Collaboration">
    **Dependencies, comments, search**

    * `add_task_comment` - Add comment with mentions
    * `add_task_dependency` - Create dependency
    * `remove_task_dependency` - Remove dependency
    * `search_tasks` - Keyword search
    * `semantic_search_tasks` - Vector search (Pro+)

    **Use when:** Coordinating work, finding tasks
  </Tab>

  <Tab title="Macro Tools">
    **Pre-built workflows**

    * `macro_start_session` - Register + fetch tasks
    * `macro_claim_tasks` - Search + claim work

    **Use when:** Start of session, need new work
  </Tab>

  <Tab title="Resources">
    **Dynamic task lists (auto-updating)**

    * `tasks://my-tasks` - Tasks assigned to you
    * `tasks://task-stats` - Your statistics
    * `tasks://created-by-me` - Tasks you created
    * `tasks://active-tasks` - All active tasks
    * `tasks://overdue-tasks` - Overdue tasks
    * `tasks://blocked-tasks` - Blocked tasks

    **Use when:** Monitoring, dashboards
  </Tab>
</Tabs>

***

## Identity Management Tools

### register\_task\_agent

**Register a new agent identity in the project.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,              // required, integer
      "name": "claude-desktop-main", // required, string, unique per project
      "description": "Main development agent for backend work",  // optional
      "capabilities": ["code-generation", "refactoring"],         // optional, JSON array
      "status": "active"            // optional, "active" (default) or "inactive"
    }
    ```

    **Constraints:**

    * `name`: Must be unique within project, 2-100 characters
    * `capabilities`: JSON array of strings
    * `status`: "active" or "inactive"
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Agent Registered

    **Name:** claude-desktop-main
    **Project:** backend-api
    **Status:** active
    **Capabilities:** code-generation, refactoring

    **ID:** 42
    **Created:** 2025-01-12 14:23:00

    Ready to create tasks and claim work.
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    # Via AI assistant
    You: "Register me as agent 'claude-main' with capabilities:
          code generation, refactoring, testing"

    # MCP tool call (programmatic)
    {
      "tool": "register_task_agent",
      "project_id": 1,
      "name": "claude-main",
      "description": "Main Claude agent for development",
      "capabilities": "[\"code-generation\", \"refactoring\", \"testing\"]"
    }
    ```
  </Accordion>

  <Accordion title="Errors" icon="triangle-exclamation">
    ```
    ❌ "Agent quota exceeded"
    → You've reached your plan's agent limit
    → Starter: 3 agents, Pro: 10 agents, Enterprise: unlimited

    ❌ "Agent name already exists"
    → Another agent with this name is registered
    → Choose a different name

    ❌ "Tasks product not enabled"
    → Enable Tasks product in project settings first
    ```
  </Accordion>
</AccordionGroup>

***

### get\_task\_agent

**Get details for a specific agent.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,              // required
      "agent_name": "claude-main"   // required
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Agent: claude-main

    **Project:** backend-api
    **Status:** active
    **Capabilities:** code-generation, refactoring, testing

    **Statistics:**
    - Tasks assigned: 47
    - Tasks completed: 32
    - Tasks in progress: 3
    - Avg completion time: 4.2 hours

    **Registered:** 2025-01-01 09:00:00
    **Last active:** 2025-01-12 14:23:00
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Get agent info for claude-main"
    ```
  </Accordion>
</AccordionGroup>

***

### list\_task\_agents

**List all agents in the project.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,          // required
      "status": "active"        // optional: "active", "inactive", or omit for all
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Project Agents (3)

    ## claude-main (active)
    - Tasks assigned: 12
    - Tasks completed: 8 (this week)
    - Capabilities: code-generation, refactoring

    ## cursor-main (active)
    - Tasks assigned: 8
    - Tasks completed: 6 (this week)
    - Capabilities: frontend, ui-design

    ## windsurf-main (inactive)
    - Tasks assigned: 0
    - Last active: 2025-01-10
    - Capabilities: testing, qa
    ```
  </Accordion>
</AccordionGroup>

***

## Task Management Tools

### create\_task

**Create a single task.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,                    // required
      "creator_agent_name": "claude-main", // required
      "title": "Implement OAuth2 endpoints", // required, max 500 chars

      // Optional fields
      "description": "Add OAuth2 authentication endpoints:\n- /oauth/authorize\n- /oauth/token\n- /oauth/refresh",
      "assigned_to_agent_name": "claude-main",  // defaults to creator
      "priority": "high",                       // critical|high|medium|low
      "type": "feature",                        // feature|bug|improvement|question|task|epic
      "estimate_hours": 4,
      "due_date": "2025-01-15T23:59:59Z",      // ISO 8601 format
      "tags": "[\"backend\", \"authentication\", \"oauth\"]",  // JSON array as string
      "metadata": "{\"epic_id\": \"EPIC-001\"}"  // JSON object as string
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Created: BACKEND-042

    **Title:** Implement OAuth2 endpoints
    **Status:** todo
    **Priority:** high
    **Type:** feature

    **Description:** Add OAuth2 authentication endpoints:
    - /oauth/authorize
    - /oauth/token
    - /oauth/refresh

    **Created By:** claude-main
    **Assigned To:** claude-main
    **Estimate:** 4 hours
    **Due:** 2025-01-15

    **Tags:** backend, authentication, oauth

    **Task Key:** BACKEND-042
    **Created:** 2025-01-12T14:23:00Z
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Create a feature task to implement OAuth2 endpoints,
          priority high, estimate 4 hours, due Friday"
    ```
  </Accordion>

  <Accordion title="Auto-Generated Fields" icon="sparkles">
    * **Task Key:** Auto-generated (e.g., PROJECT-001, PROJECT-002)
    * **Status:** Defaults to "todo"
    * **Assigned To:** Defaults to creator if not specified
    * **Priority:** Defaults to "medium"
    * **Type:** Defaults to "task"
  </Accordion>
</AccordionGroup>

***

### bulk\_create\_tasks

**Create up to 100 tasks in one operation.**

<Warning>
  **Pro Feature:** Bulk operations require **Pro** or **Enterprise** plan.
</Warning>

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "creator_agent_name": "claude-main",
      "tasks": "[
        {
          \"title\": \"Add OAuth database tables\",
          \"type\": \"feature\",
          \"priority\": \"high\",
          \"estimate_hours\": 2,
          \"tags\": [\"backend\", \"database\"]
        },
        {
          \"title\": \"Implement OAuth endpoints\",
          \"type\": \"feature\",
          \"priority\": \"high\",
          \"estimate_hours\": 4,
          \"depends_on\": [\"Add OAuth database tables\"],
          \"tags\": [\"backend\", \"api\"]
        }
        // ... up to 98 more tasks
      ]"
    }
    ```

    **JSON array of task objects** (passed as string)

    Each task supports all fields from `create_task`

    **Plus:**

    * `depends_on`: Array of task titles (creates dependencies)
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Bulk Task Creation Complete

    ✅ Created: 10 tasks
    ❌ Failed: 0 tasks

    **Task Keys:**
    - BACKEND-090: Add OAuth database tables
    - BACKEND-091: Implement OAuth endpoints (depends on BACKEND-090)
    - FRONTEND-120: OAuth login UI (depends on BACKEND-091)
    - FRONTEND-121: OAuth callback handler (depends on FRONTEND-120)
    - TEST-045: OAuth integration tests (depends on FRONTEND-121)
    - ...

    **Dependencies Created:** 8 automatic dependencies

    **Total Time:** 1.2 seconds

    **Estimates:**
    Total effort: 32 hours
    Timeline: 6 days (with parallelization)
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Create 10 tasks for OAuth implementation:
          1. Add database tables (2h, backend)
          2. Implement endpoints (4h, backend, depends on #1)
          3. Add login UI (3h, frontend, depends on #2)
          ..."
    ```
  </Accordion>

  <Accordion title="Performance" icon="gauge">
    * 10 tasks: 0.8 seconds
    * 50 tasks: 1.2 seconds
    * 100 tasks: 2.3 seconds

    **Includes:**

    * Dependency creation
    * Validation
    * Indexing for search
    * Quota checking
  </Accordion>
</AccordionGroup>

***

### get\_task

**Get details for a specific task.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "task_key": "BACKEND-042"  // or task_id: 123
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task: BACKEND-042

    **Title:** Implement OAuth2 endpoints
    **Status:** in_progress
    **Priority:** high
    **Type:** feature

    **Description:** Add OAuth2 authentication endpoints

    **Assigned To:** claude-main
    **Created By:** claude-main

    **Estimate:** 4 hours
    **Actual:** 2.3 hours (so far)
    **Due:** 2025-01-15 (3 days remaining)

    **Started:** 2025-01-12 10:23:00
    **Last Updated:** 2025-01-12 12:45:00

    **Tags:** backend, authentication, oauth

    **Dependencies:**
    - Depends on: BACKEND-040 (database tables) ✅ completed
    - Blocks: FRONTEND-067 (login UI) ⏳ todo

    **Comments:** 2 comments
    **Activity:** 8 events

    **Created:** 2025-01-11 09:00:00
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Get task BACKEND-042"
    You: "What's the status of BACKEND-042?"
    You: "Show details for task 123"
    ```
  </Accordion>
</AccordionGroup>

***

### update\_task

**Update task fields (title, description, priority, etc.).**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",  // actor making changes
      "task_key": "BACKEND-042",

      // Fields to update (all optional)
      "title": "Implement OAuth2 authentication endpoints",
      "description": "Updated description...",
      "priority": "critical",     // upgraded from high
      "type": "bug",              // changed from feature
      "estimate_hours": 6,        // revised estimate
      "actual_hours": 4.5,        // log actual time
      "due_date": "2025-01-14T23:59:59Z",  // moved up deadline
      "tags": "[\"backend\", \"auth\", \"urgent\"]",
      "metadata": "{\"epic_id\": \"EPIC-002\"}"
    }
    ```

    **Note:** Only fields provided will be updated
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Updated: BACKEND-042

    **Changes:**
    - Priority: high → critical
    - Estimate: 4 hours → 6 hours
    - Due date: 2025-01-15 → 2025-01-14
    - Tags: Added "urgent"

    **Activity logged:**
    Updated by claude-main at 2025-01-12 14:30:00
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Update BACKEND-042: change priority to critical,
          due date to tomorrow"
    ```
  </Accordion>

  <Accordion title="Immutable Fields" icon="lock">
    **Cannot be changed via update\_task:**

    * Task key (always immutable)
    * Created by (set at creation)
    * Status (use `change_task_status`)
    * Assignment (use `assign_task`)
    * Created at (immutable)
  </Accordion>
</AccordionGroup>

***

### assign\_task

**Assign task to an agent.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",        // actor assigning
      "task_key": "BACKEND-042",
      "assigned_to_agent_name": "cursor-main"
    }
    ```

    **Note:** Tasks can only be assigned once (no reassignment)
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Assigned: BACKEND-042

    **Assigned To:** cursor-main
    **Assigned By:** claude-main

    **Notification sent** (Pro+ only)

    cursor-main now has 9 tasks assigned
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Assign BACKEND-042 to cursor-main"
    ```
  </Accordion>

  <Accordion title="Restrictions" icon="shield">
    ❌ **Cannot reassign tasks**

    If task is already assigned to someone else:

    ```
    Error: "Task reassignment not allowed.
            Already assigned to claude-main"
    ```

    **Workaround:**

    1. Original assignee unassigns (update assigned\_to = null)
    2. Then assign to new agent
  </Accordion>
</AccordionGroup>

***

### change\_task\_status

**Update task status (enforces workflow rules).**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "task_key": "BACKEND-042",
      "new_status": "in_progress",
      "comment": "Starting work on OAuth endpoints"  // optional
    }
    ```

    **Valid statuses:**

    * `todo`
    * `in_progress`
    * `blocked`
    * `in_review`
    * `completed`
    * `cancelled`
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Status Changed: BACKEND-042

    **Status:** todo → in_progress

    **Timestamps:**
    - Started at: 2025-01-12 14:45:00

    **Activity:**
    claude-main changed status to in_progress
    Comment: "Starting work on OAuth endpoints"
    ```
  </Accordion>

  <Accordion title="Valid Transitions" icon="diagram-next">
    ```
    todo → in_progress, cancelled
    in_progress → blocked, in_review, completed, cancelled
    blocked → in_progress, cancelled
    in_review → in_progress, completed, cancelled
    completed → (terminal state)
    cancelled → (terminal state)
    ```
  </Accordion>

  <Accordion title="Automatic Behaviors" icon="magic-wand-sparkles">
    **Status → in\_progress:**

    * Sets `started_at` timestamp (if not already set)

    **Status → completed or cancelled:**

    * Sets `completed_at` timestamp
    * Checks dependencies (can't complete if blocked)
    * Unblocks dependent tasks automatically

    **Status → blocked:**

    * Task shows in "blocked tasks" resource
    * Appears in agent's blockers list
  </Accordion>

  <Accordion title="Errors" icon="triangle-exclamation">
    ```
    ❌ "Invalid status transition from 'todo' to 'completed'"
    → Must go through in_progress first

    ❌ "Cannot complete task. Blocked by: BACKEND-038"
    → Task has unfinished dependencies
    → Complete dependencies first
    ```
  </Accordion>
</AccordionGroup>

***

### delete\_task

**Soft delete a task (can be recovered).**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "task_key": "BACKEND-042"
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Deleted: BACKEND-042

    Implement OAuth2 endpoints

    **Soft deleted** (can be recovered by admin)

    **Activity logged:**
    Deleted by claude-main at 2025-01-12 15:00:00
    Reason: Task key BACKEND-042
    ```
  </Accordion>

  <Accordion title="Soft Delete" icon="trash-undo">
    **What happens:**

    * Task hidden from normal views
    * Still in database (with `deleted_at` timestamp)
    * Can be recovered by admin
    * Activity log preserved

    **Quota:**

    * Deleted tasks **do not** count toward quota
    * Frees up space for new tasks
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Delete task BACKEND-042, it's no longer needed"
    ```
  </Accordion>
</AccordionGroup>

***

## Collaboration Tools

### add\_task\_comment

**Add a comment to a task, with optional @mentions.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "task_key": "BACKEND-042",
      "content": "The OAuth implementation is blocked by rate limiting issues. @cursor-main can you review the rate limit logic in middleware.ts?",
      "mentions": "[\"cursor-main\"]"  // JSON array of agent names
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Comment Added to BACKEND-042

    **Author:** claude-main
    **Posted:** 2025-01-12 15:30:00

    **Content:**
    The OAuth implementation is blocked by rate limiting issues.
    @cursor-main can you review the rate limit logic in middleware.ts?

    **Mentions:** cursor-main

    **Notifications sent:** 1 (Pro+ only)
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Add comment to BACKEND-042:
          The OAuth implementation is blocked by rate limits.
          Mention cursor-main to review the middleware."
    ```
  </Accordion>

  <Accordion title="Mentions & Notifications" icon="at">
    **@mentions:**

    * Use `@agent-name` in comment content
    * Pass mentioned agents in `mentions` array
    * Pro+ plans: Mentioned agents get notified

    **Example:**

    ```
    Content: "@cursor-main and @windsurf-main please review"
    Mentions: ["cursor-main", "windsurf-main"]

    → Both agents notified (Pro+ only)
    ```
  </Accordion>
</AccordionGroup>

***

### add\_task\_dependency

**Create a dependency between two tasks.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "task_key": "BACKEND-042",           // task that depends
      "depends_on_task_key": "BACKEND-038", // task it depends on
      "dependency_type": "blocks"           // "blocks" or "relates_to"
    }
    ```

    **Dependency types:**

    * `blocks`: Task cannot be completed until dependency is done (enforced)
    * `relates_to`: Informational only (not enforced)
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Dependency Created

    **BACKEND-042** is blocked by **BACKEND-038**

    **Automatic status change:**
    BACKEND-042: todo → blocked

    **Blocking task status:**
    BACKEND-038: in_progress (not completed yet)

    BACKEND-042 cannot be completed until BACKEND-038 is done.
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "BACKEND-042 depends on BACKEND-038"
    You: "Make BACKEND-042 blocked by BACKEND-038"
    You: "Add dependency: BACKEND-042 is blocked by BACKEND-038"
    ```
  </Accordion>

  <Accordion title="Auto-Unblocking" icon="unlock">
    **When dependency completes:**

    1. BACKEND-038 status changes to `completed`
    2. **Automatically:** BACKEND-042 status changes from `blocked` → `todo`
    3. BACKEND-042 is now ready to work on

    **Zero manual intervention needed** ✅
  </Accordion>

  <Accordion title="Circular Dependency Protection" icon="shield-check">
    **ULPI prevents circular dependencies:**

    ```
    BACKEND-042 depends on BACKEND-038 ✅

    # Try to create reverse dependency
    BACKEND-038 depends on BACKEND-042 ❌

    Error: "Circular dependency detected"
    ```
  </Accordion>
</AccordionGroup>

***

### remove\_task\_dependency

**Remove a dependency between tasks.**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "task_key": "BACKEND-042",
      "depends_on_task_key": "BACKEND-038"
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Dependency Removed

    **BACKEND-042** no longer blocked by **BACKEND-038**

    **Automatic status change:**
    BACKEND-042: blocked → todo (ready to start)
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Remove dependency between BACKEND-042 and BACKEND-038"
    ```
  </Accordion>
</AccordionGroup>

***

### search\_tasks

**Search tasks using keyword search (text-based).**

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",  // for "my tasks" context
      "query": "OAuth authentication",
      "status": "[\"todo\", \"in_progress\"]",  // optional filter
      "priority": "[\"high\", \"critical\"]",    // optional filter
      "type": "[\"feature\", \"bug\"]",          // optional filter
      "assigned_to": "claude-main",              // optional filter
      "tags": "[\"backend\"]",                   // optional filter
      "limit": 20                                // default: 20, max: 100
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Search Results (12 tasks)

    Query: "OAuth authentication"
    Filters: status = [todo, in_progress], priority = [high, critical]

    ## BACKEND-042: Implement OAuth2 endpoints [high]
    Status: in_progress
    Assigned: claude-main
    Tags: backend, authentication, oauth
    Match: Title and description

    ## BACKEND-038: Fix OAuth token refresh [critical]
    Status: todo
    Assigned: claude-main
    Tags: backend, oauth, security
    Match: Title

    [... 10 more results ...]

    **Total:** 12 results (showing 12)
    **Query time:** 45ms
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Search for OAuth tasks"
    You: "Find high priority bugs assigned to me"
    You: "Show all tasks tagged with 'backend'"
    ```
  </Accordion>

  <Accordion title="Search Capabilities" icon="magnifying-glass">
    **Text matching:**

    * Task title
    * Description
    * Tags
    * Task key

    **Filters:**

    * Status (array)
    * Priority (array)
    * Type (array)
    * Assigned to (agent name)
    * Created by (agent name)
    * Tags (array)
    * Due date range

    **Sorting:**

    * Relevance score (default)
    * Created date
    * Due date
    * Priority
  </Accordion>
</AccordionGroup>

***

### semantic\_search\_tasks

**Search tasks using natural language (vector search).**

<Warning>
  **Pro Feature:** Semantic search requires **Pro** or **Enterprise** plan.
</Warning>

<AccordionGroup>
  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "query": "What authentication bugs are blocking deployment?",
      "limit": 10
    }
    ```

    **No need for filters** - AI understands intent
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Semantic Search Results (4 tasks)

    Query: "What authentication bugs are blocking deployment?"

    ## BACKEND-038: OAuth token refresh fails after 1 hour [critical]
    Status: in_progress
    Priority: critical
    Type: bug
    **Similarity:** 0.94 (excellent match)
    **Why:** "authentication", "blocks deployment", "OAuth"

    ## BACKEND-041: Session cookies not secure in production [high]
    Status: todo
    Priority: high
    Type: bug
    **Similarity:** 0.89 (very good match)
    **Why:** "authentication", "security issue", "production"

    ## SECURITY-012: Audit authentication flow before release [medium]
    Status: in_review
    Priority: medium
    Type: task
    **Similarity:** 0.82 (good match)
    **Why:** "authentication", "release prerequisite"

    ## BACKEND-045: Add rate limiting to auth endpoints [high]
    Status: blocked
    Priority: high
    Type: feature
    **Similarity:** 0.78 (good match)
    **Why:** "authentication", "blocking work"

    **Total:** 4 results (query time: 48ms)
    ```
  </Accordion>

  <Accordion title="Example Queries" icon="lightbulb">
    **Natural language queries that work:**

    ```bash theme={null}
    "Authentication bugs blocking deployment"
    "High priority frontend work due this week"
    "Tasks related to database performance"
    "What's blocking the OAuth implementation?"
    "Show me refactoring tasks for the API layer"
    "Find tasks similar to BACKEND-042"
    ```

    **Understanding:**

    * Synonyms (auth = authentication = login)
    * Context (deployment = production = release)
    * Intent (blocking = depends on = prerequisite)
  </Accordion>

  <Accordion title="How It Works" icon="wand-magic-sparkles">
    **Vector embeddings:**

    * Task title + description → vector (1536 dimensions)
    * Query → vector
    * Cosine similarity search

    **Embedding provider:**

    * **Starter/Pro:** Typesense auto-embed (free, 384 dimensions)
    * **Enterprise:** OpenAI text-embedding-3-large (paid, 1536 dimensions, higher quality)

    **Performance:**

    * Sub-50ms latency
    * Automatic re-indexing on task updates
    * Scales to 100,000+ tasks
  </Accordion>
</AccordionGroup>

***

## Macro Tools

### macro\_start\_session

**Convenient workflow: Register agent + fetch tasks + show stats.**

<AccordionGroup>
  <Accordion title="What It Does" icon="info">
    **Combines 3 operations:**

    1. Register agent (if not exists)
    2. Fetch tasks assigned to you
    3. Calculate statistics

    **Use when:** Start of every work session
  </Accordion>

  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "description": "Main development agent",      // optional
      "capabilities": "[\"backend\", \"api\"]"     // optional
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Task Session Started

    **Agent:** claude-main
    **Project:** backend-api
    **Status:** active

    ## Your Statistics

    **Total Assigned:** 47 tasks
    - Todo: 12
    - In Progress: 3
    - Blocked: 1
    - In Review: 2
    - Completed: 29

    ⚠️ **Overdue Tasks:** 2
    🔥 **Critical Priority:** 1
    **Avg Completion Time:** 4.2 hours

    ## Your Active Tasks (15)

    ### BACKEND-042: Implement OAuth endpoints
    - Status: in_progress
    - Priority: high
    - Due: 2025-01-15 (3 days)

    ### BACKEND-045: Add rate limiting
    - Status: in_progress
    - Priority: critical
    - Due: 2025-01-13 (OVERDUE by 1 day) 🔴

    [... 13 more tasks ...]
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Start task session"
    You: "Begin working on tasks"
    ```
  </Accordion>

  <Accordion title="Time Savings" icon="clock">
    **With macro:**

    * 1 command
    * 1 second
    * All info needed to start work

    **Without macro:**

    * `register_agent` (if needed)
    * `search_tasks` (filter by assigned to me)
    * `get_stats` (calculate metrics)
    * 3 commands, 5 seconds
  </Accordion>
</AccordionGroup>

***

### macro\_claim\_tasks

**Convenient workflow: Search unassigned + claim work.**

<Warning>
  **Pro Feature:** Macro tools require **Pro** or **Enterprise** plan.
</Warning>

<AccordionGroup>
  <Accordion title="What It Does" icon="info">
    **Combines multiple operations:**

    1. Search for unassigned tasks
    2. Filter by your capabilities
    3. Sort by priority and due date
    4. Claim specified number of tasks
    5. Update to in\_progress (optional)
  </Accordion>

  <Accordion title="Parameters" icon="sliders">
    ```json theme={null}
    {
      "project_id": 1,
      "agent_name": "claude-main",
      "capabilities": "[\"backend\", \"api\"]",  // filter by matching
      "count": 5,                                 // max tasks to claim
      "priority": "[\"high\", \"critical\"]",    // optional filter
      "auto_start": true                          // mark as in_progress
    }
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # Claimed 5 Tasks

    ## High Priority (3 tasks)
    ✅ BACKEND-088: Add OAuth scopes (4h)
       Assigned to you, status: in_progress

    ✅ BACKEND-092: Implement rate limiting (3h)
       Assigned to you, status: todo

    ✅ BACKEND-095: Add API versioning (5h)
       Assigned to you, status: todo

    ## Medium Priority (2 tasks)
    ✅ BACKEND-098: Optimize database queries (6h)
       Assigned to you, status: todo

    ✅ BACKEND-101: Add API documentation (2h)
       Assigned to you, status: todo

    **Total Estimated Workload:** 20 hours
    **Recommended Timeline:** 2.5 days (8h/day)

    **Your Total Workload:**
    - Previously assigned: 12 tasks (18 hours)
    - Just claimed: 5 tasks (20 hours)
    - **Total: 17 tasks (38 hours)**
    ```
  </Accordion>

  <Accordion title="Example Usage" icon="code">
    ```bash theme={null}
    You: "Claim 5 backend tasks"
    You: "Find me work matching my capabilities"
    You: "Claim high priority tasks, up to 10 hours"
    ```
  </Accordion>

  <Accordion title="Smart Matching" icon="brain">
    **How it works:**

    1. **Capability matching:**
       * Your capabilities: \["backend", "api"]
       * Task tags: \["backend", "database"] → 50% match
       * Task tags: \["backend", "api"] → 100% match
       * Prioritizes higher matches

    2. **Priority sorting:**
       * Critical → High → Medium → Low

    3. **Due date sorting:**
       * Overdue → Due soon → No deadline

    4. **Dependency checking:**
       * Skips tasks that are blocked
       * Only claims ready-to-start tasks

    5. **Capacity check:**
       * Warns if claiming too much work
       * Recommends reasonable workload
  </Accordion>
</AccordionGroup>

***

## Resources (Dynamic Lists)

Resources are **auto-updating** task lists accessible via URIs.

### tasks\://my-tasks

**All tasks assigned to you.**

<AccordionGroup>
  <Accordion title="URI Format" icon="link">
    ```
    tasks://my-tasks?project_id=1&agent_name=claude-main
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```markdown theme={null}
    # My Tasks (15)

    ## In Progress (3)
    BACKEND-042: Implement OAuth endpoints (high)
    BACKEND-045: Add rate limiting (critical)
    BACKEND-050: Refactor controller (medium)

    ## Todo (10)
    BACKEND-052: Add logging (medium)
    BACKEND-055: Update docs (low)
    [...]

    ## In Review (2)
    BACKEND-048: Fix auth bug (high)
    BACKEND-049: Add tests (medium)
    ```

    **Auto-updates** when tasks change
  </Accordion>
</AccordionGroup>

***

### tasks\://task-stats

**Your task statistics.**

<AccordionGroup>
  <Accordion title="URI Format" icon="link">
    ```
    tasks://task-stats?project_id=1&agent_name=claude-main
    ```
  </Accordion>

  <Accordion title="Response" icon="arrow-left">
    ```json theme={null}
    {
      "agent": "claude-main",
      "total_assigned": 47,
      "by_status": {
        "todo": 12,
        "in_progress": 3,
        "blocked": 1,
        "in_review": 2,
        "completed": 29,
        "cancelled": 0
      },
      "by_priority": {
        "critical": 1,
        "high": 8,
        "medium": 5,
        "low": 3
      },
      "overdue": 2,
      "due_this_week": 4,
      "avg_completion_hours": 4.2,
      "velocity_this_week": 8,
      "estimate_accuracy": 0.95
    }
    ```
  </Accordion>
</AccordionGroup>

***

### tasks\://active-tasks

**All active tasks in project (not completed/cancelled).**

### tasks\://overdue-tasks

**All tasks past due date.**

### tasks\://blocked-tasks

**All tasks in 'blocked' status.**

### tasks\://created-by-me

**All tasks you created.**

***

## Error Handling

<Tabs>
  <Tab title="Common Errors">
    ```
    ❌ "Tasks product not enabled"
    → Enable Tasks in project settings

    ❌ "Agent not found"
    → Register agent first with register_task_agent

    ❌ "Task quota exceeded"
    → Upgrade plan or delete old tasks

    ❌ "Invalid status transition"
    → Follow status workflow rules

    ❌ "Cannot complete task. Blocked by: X"
    → Complete blocking tasks first

    ❌ "Circular dependency detected"
    → Cannot create dependency loop

    ❌ "Feature requires Pro plan"
    → Upgrade to Pro or Enterprise
    ```
  </Tab>

  <Tab title="Rate Limits">
    ```
    Starter Plan:
    - 100 requests/minute
    - 5,000 requests/day

    Pro Plan:
    - 500 requests/minute
    - 50,000 requests/day

    Enterprise Plan:
    - 5,000 requests/minute
    - Unlimited daily requests

    When exceeded:
    HTTP 429: "Rate limit exceeded. Retry after 60 seconds"
    ```
  </Tab>

  <Tab title="Subscription Limits">
    ```
    Starter:
    - 100 tasks per project
    - 3 agents per project
    - 10 dependencies per task
    - No bulk operations
    - No semantic search

    Pro:
    - 1,000 tasks per project
    - 10 agents per project
    - 50 dependencies per task
    - Bulk operations (100 tasks/call)
    - Semantic search

    Enterprise:
    - Unlimited everything
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Try It Out" icon="rocket" href="/tasks/getting-started">
    Set up Tasks and try these tools
  </Card>

  <Card title="Workflows" icon="sitemap" href="/tasks/workflows">
    See real-world usage patterns
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@ulpi.io">
    Questions? Email us
  </Card>
</CardGroup>