projects
Read and update a team's objective board: track goals, key results, owners, stages, progress, budgets, and which work pays into each result.
Instructions
Projects | the caller's OWN project board with its objectives and key results, read and written deterministically (no LLM on this path): what a team agreed to achieve, what it works on, who works on it, how far along it is, and which key result each piece of work pays into. Call it for "what is my team working on", "which key result has no project behind it", "what does marketing contribute", "which projects are off track", "what is undecided", or to add or move a project, objective or key result.
PROJECTS: "list" folds the board on ONE axis, group = okr (default) | country | function | person. On person a project appears under its owner and every contributor; on the other axes once. Nothing set on the axis lands in a NAMED group ("No country set"), never dropped. Undecided projects come back in inbox. "get" returns one project with milestones and KPIs; "create" adds one; "update" changes one (stage, progress, traffic light, dates, parent, budget, effort, impact, key_result_id). A project carries a target date (due sentence derived on read), a parent (three levels at most), prerequisites (blocked_by), a budget in its own currency (never converted), effort in days and impact 1 to 5; sort = effort_impact orders by impact then effort without a score.
OBJECTIVES: "objectives" returns every objective with its key results: value, source (dataset or manual), a DERIVED status (on track, at risk, off track, no data yet; from baseline, target, direction and time left, never set by hand, and no value is never on track), guardrails, target history and the projects behind it. "create_objective" needs title; "update_objective" needs id; "create_key_result" needs objective_id, title, target (or country_values); "update_key_result" needs id. Changing a target needs target_reason (ten characters or more) and is kept in a history nothing rewrites. A key result may carry values per country (country_values) and says how they add up (aggregation); with country values its target and current are DERIVED from them (sum, average, or none = no total, country_total says how many countries reported) and a typed target is ignored, and with country_column a dataset-bound key result reads value_column once per country. A key result with guards_id is a GUARDRAIL: breached, the guarded key result is off track even at full attainment.
THE VALUE RULE for KPIs and key results: EITHER a typed number OR read live from a column of any dataset on this account, such as a Google Search Console, Shopify or World Bank table or an uploaded CSV (dataset_id + value_column, optionally filter_column + filter_value), never both. A value that cannot be read is null with a reason, never zero.
NEVER: it never derives the traffic light or progress of a project (a person sets both), never invents a key result (link one of the account key results by key_result_id; list returns them as key_results), and never reaches another account: a foreign id answers not found. On a shared board a member with the editor role is a project lead: the board admin decides which fields a lead may change, and a refused field answers 403 naming it. Requires the caller's own autario account (API key or OAuth).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The id of the thing to read or change: the project for "get" and "update", the objective for "update_objective", the key result for "update_key_result". | |
| kind | No | Is this a project with an end, or recurring day-to-day work? Default "project". | |
| sort | No | For "list": the order of cards inside each group. "board" (default) puts off-track work first; "effort_impact" orders by impact (5 to 1) then effort (fewest days first), unrated work last. No combined score is computed. | |
| unit | No | For key results: the unit the number is in. | |
| brief | No | A short description of what the project is. | |
| group | No | For "list": which axis the cards are folded on. Default "okr", which is the axis that answers "does everything we do pay into something we agreed". | |
| owner | No | The one person accountable for it. | |
| stage | No | Where it stands. A new project starts "active" (running); when the board owner switched on "New projects need admin approval", a non-admin's new project starts at "inbox" (pending review) and only an admin moves it out. "long_list" = agreed, not started; "done" = finished. | |
| title | No | Project title. Required for "create". | |
| action | No | What to do. Default "list". | |
| format | No | Output wire format for this MCP call. Default 'toon' (Token-Oriented Notation, fewest tokens, best for tabular rows). 'compact' = minified JSON. 'json' = pretty JSON for readability. The REST API always returns JSON regardless. | |
| impact | No | Expected impact as a judgement: 1 low, 2 some, 3 clear, 4 high, 5 very high. | |
| status | No | The traffic light, set by a person: on track, at risk, off track. | |
| target | No | For key results: the number that counts as done. Required on create. | |
| country | No | The region or country that runs it, in the account's own words ("DACH", "Nordics"), not an ISO code. | |
| ends_on | No | For objectives: end of that window, YYYY-MM-DD. | |
| baseline | No | For key results: where the number started. Attainment runs from baseline to target. | |
| function | No | The function that contributes it ("Marketing", "Supply chain"). | |
| direction | No | For key results: whether higher or lower is better. Default increase. | |
| guards_id | No | For key results: makes this key result a GUARDRAIL of that key result. | |
| parent_id | No | The project this one is part of. Projects nest at most three levels deep (programme, workstream, piece); a move that would make a fourth level or a loop is refused with a sentence. Parent progress, when the parent has none of its own, is the mean of its children and says so. | |
| starts_on | No | For objectives: start of the window its key results are paced against, YYYY-MM-DD. | |
| commitment | No | For objectives: committed (expected at 1.0) or aspirational (0.7 is a good outcome). Changes the status rule of its key results, never a number. | |
| dataset_id | No | For key results: the dataset the value is read from (any dataset on this account). | |
| started_at | No | Start date, YYYY-MM-DD. | |
| aggregation | No | For key results: how its countries add up to a region. sum (default) for counts and money, average for rates and levels, none lists the countries without a total. | |
| effort_days | No | Estimated effort in person days. | |
| target_date | No | Target date, YYYY-MM-DD. "Due in N days" / "overdue by N days" is derived from it on every read and never stored. | |
| contributors | No | Everyone else working on it. These names are what the person axis groups by, together with the owner. | |
| filter_value | No | For key results: the value filter_column must have. | |
| manual_value | No | For key results: the current value typed by hand. Shown as typed by hand; prefer dataset_id + value_column. | |
| objective_id | No | For "create_key_result": the objective it belongs to. "objectives" lists them. | |
| progress_pct | No | Progress in percent, 0 to 100, set by a person. Never derived from milestones or dates. | |
| spent_amount | No | Money spent so far, typed by a person, in budget_currency. | |
| value_column | No | For key results: the column of dataset_id that holds the number. | |
| budget_amount | No | Budget. Needs budget_currency. Never converted between currencies. | |
| filter_column | No | For key results: optional column to filter the dataset on. | |
| key_result_id | No | The id of the key result this project pays into. "list" returns the linkable ones in `key_results`; pass one of their `id` values. Omit for work that pays into nothing yet, which is exactly what the OKR axis is there to make visible. | |
| resources_url | No | A link to where the actual work lives (a drive folder, a board, a doc). http(s) only. | |
| target_reason | No | For "update_key_result": why the target moves (ten characters or more). Required whenever `target` changes; the change is kept in the key result history. | |
| country_column | No | For key results with dataset_id: the column that names the country of a row (autario_entity when the dataset has it). value_column is then read per country; a country the dataset lacks keeps its typed value. | |
| country_values | No | For key results: the value per country, [{ country, current, target }]; country as a name or ISO code. A region total uses these; several countries without values are never split. | |
| guardrail_note | No | For key results: how this number could be reached the wrong way. | |
| budget_currency | No | Three letter currency code of the budget, e.g. EUR. |