Skip to main content

Goals Tools

Tools for managing goals across different time horizons.

Personal Goals

Goals are personal to each user. All goal operations are automatically scoped to the authenticated user—you can only view, create, update, and delete your own goals. This allows agents to help manage your personal objectives without exposing them to others in your workspace.

Available Tools​

goals_list​

List goals in a workspace.

{
  "name": "goals_list",
  "arguments": {
    "workspace_id": "ws_123",
    "space_id": "space_456",        // optional
    "horizon": "mid",               // optional: short, mid, long
    "include_tasks": true           // optional
  }
}

Response:

{
  "goals": [
    {
      "id": "goal_789",
      "title": "Launch API v2.0",
      "description": "Complete API redesign with new endpoints",
      "horizon": "mid",
      "keywords": ["api", "release"],
      "taskCount": 8,
      "completedTaskCount": 5,
      "progress": 62.5,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

goals_create​

Create a new goal.

{
  "name": "goals_create",
  "arguments": {
    "workspace_id": "ws_123",
    "space_id": "space_456",
    "title": "Launch API v2.0",
    "description": "Complete API redesign with new endpoints",
    "horizon": "mid",
    "keywords": ["api", "release"]
  }
}

Response:

{
  "goal": {
    "id": "goal_789",
    "title": "Launch API v2.0",
    "description": "Complete API redesign with new endpoints",
    "horizon": "mid",
    "keywords": ["api", "release"],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

goals_get​

Get details of a specific goal.

{
  "name": "goals_get",
  "arguments": {
    "workspace_id": "ws_123",
    "goal_id": "goal_789",
    "include_tasks": true
  }
}

Response:

{
  "goal": {
    "id": "goal_789",
    "title": "Launch API v2.0",
    "description": "Complete API redesign with new endpoints",
    "horizon": "mid",
    "keywords": ["api", "release"],
    "tasks": [
      {
        "id": "task_001",
        "title": "Implement OAuth",
        "status": "done"
      },
      {
        "id": "task_002",
        "title": "Add rate limiting",
        "status": "in_progress"
      }
    ],
    "progress": 62.5
  }
}

goals_update​

Update an existing goal.

{
  "name": "goals_update",
  "arguments": {
    "workspace_id": "ws_123",
    "goal_id": "goal_789",
    "title": "Launch API v2.0 Beta",
    "description": "Updated description",
    "horizon": "short",
    "keywords": ["api", "beta"]
  }
}

goals_delete​

Delete a goal.

{
  "name": "goals_delete",
  "arguments": {
    "workspace_id": "ws_123",
    "goal_id": "goal_789"
  }
}

Link a task to a goal.

{
  "name": "goals_link_task",
  "arguments": {
    "workspace_id": "ws_123",
    "goal_id": "goal_789",
    "task_id": "task_001"
  }
}

Remove a task from a goal.

{
  "name": "goals_unlink_task",
  "arguments": {
    "workspace_id": "ws_123",
    "goal_id": "goal_789",
    "task_id": "task_001"
  }
}

Goal Horizons​

HorizonTypical TimeframeUse Case
shortWeeksSprint goals, weekly objectives
midMonths/QuarterProject milestones, quarterly goals
longYear+Strategic initiatives, vision

Example: Project Planning​

// Create a long-term goal
const longGoal = await mcp.call("goals_create", {
  workspace_id: "ws_123",
  space_id: "space_456",
  title: "Become market leader in AI docs",
  horizon: "long",
  keywords: ["strategy", "growth"]
});

// Create supporting mid-term goal
const midGoal = await mcp.call("goals_create", {
  workspace_id: "ws_123",
  space_id: "space_456",
  title: "Launch enterprise features",
  horizon: "mid",
  keywords: ["enterprise", "features"]
});

// Link tasks to goal
await mcp.call("goals_link_task", {
  workspace_id: "ws_123",
  goal_id: midGoal.goal.id,
  task_id: "task_sso"
});

// Check progress
const progress = await mcp.call("goals_get", {
  workspace_id: "ws_123",
  goal_id: midGoal.goal.id,
  include_tasks: true
});