Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
WRITE

suggest_estimate

Asks Heimdall how big one work item is in story points, against the items the project already sized, with a confidence and the anchors it compared with; writes nothing and spends the team's AI budget.

Ask Heimdall for a size before the person points an item. Give work_item_id. The assist reads the item (its kind, title, story sentence, description, acceptance criteria and any estimate in hours), the project's story point scale, and up to five items the project already sized that resemble it most by the words they share, each with its points and status. It answers with points, one step of the scale exactly as the project writes it, a confidence between 0 and 1, a rationale that names the items it compared with by reference and says what makes this one bigger, smaller or the same, and the nearest items with used marking the ones it leaned on. A number off the scale is snapped to the nearest step; a size the scale has no step for comes back as points: null with the rationale, which is Heimdall saying the item is too vague to size.

Nothing is written. Read the size and the reasons back to the person, and write the points they settle on through update_work_item with story_points. The call spends the team's monthly AI budget; ask once per item, and ask again only after the item changed. It needs ai:use, a staff token whose holder may change items on the project, and the project's assists on.

Requires ability

ai:use

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

POST/v1/work-items/{item}/estimate-suggestions

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Arguments

work_item_id*string

UUID of the work item to size.

What it returns

{  "data": {    "points": "5",    "confidence": 0.82,    "rationale": "It mirrors CRM-118 almost line for line and adds the expiry rule from CRM-121; the same screens, one more branch.",    "nearest": [      {        "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",        "reference": "CRM-118",        "title": "Apply a gift card at checkout",        "type": "Story",        "points": "5",        "status": "Done",        "similarity": 0.4,        "used": true      },      {        "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7081",        "reference": "CRM-121",        "title": "Refuse an expired voucher",        "type": "Story",        "points": "3",        "status": "Done",        "similarity": 0.17,        "used": true      },      {        "id": "f6a7b8c9-d0e1-4f2a-8b3c-4d5e6f708192",        "reference": "CRM-104",        "title": "Export the monthly invoices",        "type": "Story",        "points": "8",        "status": "Done",        "similarity": 0,        "used": false      }    ],    "scale": "fibonacci",    "steps": ["1", "2", "3", "5", "8", "13", "21"]  }}

How it fails

VALIDATION_FAILED

Heimdall could not reach its model; nothing was filed or written, and a retry a moment later is safe.

RESOURCE_NOT_FOUND

unknown work_item_id, or an item of a project outside the token's scope or the person's visibility.

FORBIDDEN

the 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_EXHAUSTED

the team's monthly AI budget has no room; a team admin raises it under Settings → AI.

TOKEN_MISSING_ABILITY

token lacks ai:use.

Related

get_work_itemthe item and its criteria the size is about; a vague item sizes badly, so read it first.update_work_itemwrite the points the person settles on.review_qualitywhen the confidence is low, a quality review says what the item is missing.suggest_sprint_scopethe planner that counts the points once they are set.Work items APIthe same suggestion over REST under the item's estimate suggestions endpoint.

How is this guide?

Last updated on