suggest_sprint_scope
Asks Heimdall's sprint planner to propose a scope for a planned or running sprint from the open backlog, within the capacity and with a reason per item; plans nothing and spends the team's AI budget.
Ask Heimdall for a first cut of a sprint before the person plans it. Give sprint_id. The planner reads the sprint's goal, dates, capacity in points and hours and the project's working days, the average velocity of the last three closed sprints, and every open backlog item in no sprint with its kind, priority, points, estimate, due date, whether its Definition of Ready is complete and the open items that block it. It answers with the items to take in order (items, each with one sentence on why), the ones to leave out and the rule that left them (left_out), the risks of the scope it picked, the total_points picked against the capacity_points, the velocity it leaned on and how many candidates it was offered. Only ids among the candidates survive: anything else the model names is dropped before you see it.
Nothing is planned. Read the proposal back to the person, and put the items they agree to into the sprint through update_work_item with the sprint_id, one item at a time, or let them tick the proposal on the Sprints page. The call spends the team's monthly AI budget, so ask once per planning conversation, not once per question; a sprint that is with the team, completed or cancelled is refused, as is a backlog with nothing left to plan. It needs ai:use, a staff token whose holder may change items on the project, and the project's assists on.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Arguments
sprint_id*stringUUID of the planned or running sprint to plan.
What it returns
{ "data": { "summary": "The two voucher stories fill the ten points and finish the checkout goal; the invoice export waits for the ledger service, which is still in Sprint 3.", "items": [ { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "reference": "CRM-142", "title": "Apply a voucher at checkout", "type": "Story", "priority": "High", "points": 5, "due_on": null, "ready": true, "blocked_by": [], "reason": "Highest priority, ready, and the first half of the sprint goal." }, { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "reference": "CRM-143", "title": "Refuse an expired voucher", "type": "Story", "priority": "Medium", "points": 5, "due_on": "2026-11-15", "ready": false, "blocked_by": [], "reason": "Due inside the sprint; one entry of its Definition of Ready is still unticked and must be closed first." } ], "left_out": [ { "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "reference": "CRM-150", "title": "Export invoices", "type": "Story", "priority": "Medium", "points": 8, "due_on": null, "ready": true, "blocked_by": ["CRM-131"], "reason": "Blocked by CRM-131, which is not a candidate; rule four." } ], "risks": [ "CRM-143 is not ready yet; close its Definition of Ready before the sprint starts.", "Both stories touch the checkout; test them together." ], "total_points": 10, "capacity_points": 10, "capacity_hours": null, "velocity": 10, "candidate_count": 3 }}How it fails
VALIDATION_FAILEDthe sprint takes no more items (it is with the team, completed or cancelled), every open item of the backlog is already in a sprint, or Heimdall could not reach its model; nothing was filed, and a retry a moment later is safe.
RESOURCE_NOT_FOUNDunknown sprint_id, or a sprint of a project outside the token's scope.
FORBIDDENthe token is a client guest's, the holder may not change items on the project or the role does not carry ai:use, or the project's assists are off.
AI_BUDGET_EXHAUSTEDthe team's monthly AI budget has no room; a team admin raises it under Settings → AI.
TOKEN_MISSING_ABILITYtoken lacks ai:use.
Related
How is this guide?
Last updated on