5 gateway tools. 319 actions on demand.

whoami

Who this credential acts as: user id, name, email, org id, role, the teams the caller belongs to, and the permission grants the credential actually carries. Start here to find out what you are allowed to do.

global_search

Ranked title and body matches across visions, strategies, objectives, metrics, opportunities, tasks, customers, insights, teams, and users, each with its ref and parent. Only the entity types you hold the read capability for are searched, so a narrow key sees a narrow result set. Needs at least 2 characters and returns at most 40 results; use the per-entity list actions to page a single type.

• q: string — Search text; at least 2 characters
• perTypeLimit?: integer | string — Max results per entity type, 1-20 (default 8)

list_visions

List strategic visions with cursor pagination: the company vision first, then product visions. Optionally filter by kind (company, product).

• kind?: "company" | "product" — Vision kind filter
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_vision

Get a vision by UUID or by its per-org ref (VIS-12).

• id: uuid | string — Vision UUID or ref (VIS-12)

list_vision_versions

Version snapshots of a vision, newest first, with cursor pagination. Every name or narrative edit creates one.

• id: uuid — Vision UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_vision_objectives

The objectives anchored to this vision, with cursor pagination. Returns objective rows, so it needs objective:read as well as vision:read.

• id: uuid — Vision UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

count_vision_children

Blast radius of a vision: how many objectives, opportunities and tasks hang off it. Objectives link by FK; opportunities and tasks by their visionPath prefix. 404 when the vision is not one of yours — zero children and no such vision are different answers.

• id: uuid — Vision UUID

list_objectives

List strategic objectives with cursor pagination. Filter by vision, by the metric they are anchored to, by DRI (pass your own user id from whoami for 'my objectives'), or by status.

• visionId?: uuid — Vision UUID filter
• metricId?: uuid — Anchor metric UUID filter
• driId?: uuid — DRI user UUID filter
• status?: "active" | "achieved" | "abandoned" — Objective status filter. One of: active, achieved, abandoned
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_objective

Get an objective by UUID or by its per-org ref (OBJ-12).

• id: uuid | string — Objective UUID or ref (OBJ-12)

get_objective_opportunities

The complete set of opportunities linked to this objective, with their link metadata, alphabetically by title. Not paginated: it is a roll-up of one objective's trace, ordered on a value derived after the query, so there is no stable cursor to page it on. Use `list_opportunities` for a paged walk of the org's opportunities.

• id: uuid — Objective UUID

get_objective_alignment

Every objective in the org as a column, plus the objectives and non-cancelled opportunities that claim to move them as rows. Each row carries `serves`: one entry per objective it advances, with kind 'primary' (this is what the row is really for) or 'supporting'. A primary objective→objective link is also the nesting parent. Not paginated: columns, rows and marks are one picture and a page cursor would draw a lying one; it is clamped instead. Use `list_objectives` for a paged walk.

get_objective_nesting

The objective one level up (`parent`), the objectives one level down (`children`), and the supporting ties in both directions (`alsoServes`, `supportedBy`). Nesting is one level deep, so this is the whole tree around an objective, not a slice of it. Not paginated: it is bounded by the org's objective count and read as one shape.

• id: uuid — Objective UUID

get_objective_claims

Every open customer insight tied to this objective, each with its estimated delta, committed date and the work items that satisfy it (conditionStatus: no_work, in_progress, delivered, broken). Not paginated: the claim set is assembled from three queries and ordered after the fact, so there is no stable cursor to page it on. Use `list_insights --objective-id` for a paged walk of the same insights.

• id: uuid — Objective UUID

list_metrics

List metrics tracked by the organisation, with cursor pagination. Filter by steward (pass your own user id from whoami for 'my metrics').

• stewardId?: uuid — Steward user UUID filter
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_metric

Get a metric by UUID or by its per-org ref (MET-12).

• id: uuid | string — Metric UUID or ref (MET-12)

list_metric_values

Recorded values for a metric, oldest first, with cursor pagination over the whole series. Optionally filter by date (since).

• id: uuid — Metric UUID
• since?: string — Only values recorded at or after this time
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_builtin_metrics

The catalog of metrics Telos computes from its own data (task throughput, lead/cycle time, time in status, cycle predictability), with whether each is already tracked in this workspace.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_metric_opportunities

The complete set of opportunities that reach this metric through the objectives anchored to it, alphabetically by title. Not paginated: it is a roll-up of one metric's trace, ordered after the query, so there is no stable cursor to page it on. Use `objective list --metric-id` for the objectives themselves, and `list_opportunities` when you want a paged walk. 404 when the metric is not one of yours — an empty list means nobody is betting on it.

• id: uuid — Metric UUID

get_metric_dependents

Blast radius before deleting or re-anchoring a metric: how many opportunities and objectives it carries, and how many of those opportunities are still live bets.

• id: uuid — Metric UUID

list_strategies

List strategies with cursor pagination. Optionally filter by status (draft, active, archived).

• status?: "draft" | "active" | "archived" — Strategy status filter
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_strategy

Get a strategy by UUID or by its per-org ref (STR-12).

• id: uuid | string — Strategy UUID or ref (STR-12)

list_strategy_versions

Version snapshots of a strategy, newest first, with cursor pagination. Every content edit creates one.

• id: uuid — Strategy UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_direction_documents

List direction documents with cursor pagination: visions, strategies, product specs and context documents in one store, newest edit first. Filter by kind, vision scope or status. Rows carry the ref and a contentHash of the body, never the body itself. Kinds you cannot read are omitted, so this needs vision:read or strategy:read alongside direction:read to see those two.

• kind?: "vision" | "strategy" | "product_spec" | "context" — Document kind filter
• scope?: "company" | "product" — Vision scope filter (company or product); only visions carry one
• status?: "draft" | "published" | "archived" — Document status filter
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_direction_changes

Every published version across the direction store, newest first, with cursor pagination. Each row names the document, its ref and kind, the version, who changed it and their note; isCreation marks version 1. Kinds you cannot read are omitted.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_direction

Get one direction document by UUID or by its per-org ref (VIS-1, STR-2, SPEC-3, CTX-4). Returns the published body alongside the list fields; the unpublished draft is a separate read.

• id: uuid | string — Direction document UUID or ref (VIS-1, STR-2, SPEC-3, CTX-4)

get_direction_draft

The unpublished working copy of a direction document, or null when there is none, together with nextVersion: the version number a publish would write.

• id: uuid — Direction document UUID

list_direction_versions

Version snapshots of one direction document, newest first, with cursor pagination. Every publish writes one, carrying the title and body as they stood.

• id: uuid — Direction document UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_opportunities

List opportunities with cursor pagination. Optionally filter by lifecycle state or team.

• state?: "backlog" | "in_progress" | "completed" | "cancelled" — Opportunity lifecycle state filter
• teamId?: uuid — Team UUID filter
• leadUserId?: uuid — Lead UUID filter. Pass your own user id (whoami) for 'my opportunities'
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_opportunity

Get a specific opportunity by id.

• id: uuid — Opportunity UUID

list_opportunity_tasks

The tasks attached to this opportunity, with cursor pagination.

• id: uuid — Opportunity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_opportunity_context

Get everything needed to act on an opportunity in one call: the opportunity and PRD, linked objectives, the customer(s), comments, linked insights, the active template step, and any linked PRs. Sections you lack the read capability for (e.g. customers, insights) come back null. Pass the opportunity ref (e.g. OPP-23).

• ref: string — Opportunity ref, e.g. OPP-23

get_opportunity_scorecard

Get an opportunity's scorecard: the org's active scoring criteria (name, normalized decimal weight, invert), the shared 1-5 values with attribution, and the computed 0-100 total (null until every non-zero-weight criterion is scored). Positive active weights sum to 1 and correspond to the percentages shown in Settings; zero-weight criteria do not affect the total.

• id: uuid — Opportunity UUID

list_opportunity_updates

The status updates posted on this opportunity, newest first. These are the same rows that reach every linked customer's feed; plain discussion comments are separate.

• id: uuid — Opportunity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_opportunity_risks

The four validation risks (value, usability, feasibility, viability) for one opportunity: each risk's aggregate and every teammate's vote with its note.

• id: uuid — Opportunity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_opportunity_scoring_criteria

The org's scorecard criteria (name, weight, invert, order) — the inputs every opportunity scorecard is scored against. Positive active weights are normalized decimal shares that sum to 1 (the Settings surface shows the same values as percentages totaling 100%); a newly added zero-weight criterion is allocation-neutral. Read-only on the wire, and a pure read: defining criteria is a workspace-settings act gated on scoring_criteria:manage and kept in-app, so an org that has never configured scoring answers with an empty list rather than being seeded by your GET.

• includeArchived?: boolean | "true" | "false" — Include archived criteria (kept for historical scores)
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_opportunity_phases

An opportunity's phases in delivery order. A phase is a milestone, not work: it carries a title, an owner, and one target date, and it spawns no task. Its band on the plan runs from the previous phase's target to its own, and is open ended when it has none. taskCount and doneCount count only leaf tasks - work with no live children - because a task with children is a container and counting both would report the same work twice; cancelled and duplicate work is left out of the ratio entirely, since it can never complete. Set a task's phase with update_task.

• id: uuid — Opportunity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

count_unphased_opportunity_tasks

How many of an opportunity's top level tasks no phase claims. Work is never hidden by being unphased - it is its own group at the end of the arc - so this is what says whether that group exists at all. Counts top level tasks only, for the same reason list_opportunity_phases counts leaves: a container and its children are one piece of work, not two.

• id: uuid — Opportunity UUID

get_task_planned_work_summary

Coverage of the planned work in one window: how much of it carries an explicit estimate, a planning window, an opportunity tie, and current source data. Estimate values are totalled per team and per unit and are never blended across either.

• teamIds?: string[] | string — Telos team UUIDs to scope the read to; omit for every team
• cycleId?: uuid — Cycle UUID as the planning window
• jiraSprintId?: uuid — Jira sprint UUID as the planning window
• start?: string — Planning window start (YYYY-MM-DD)
• end?: string — Planning window end, exclusive (YYYY-MM-DD)

get_task_planned_work_gaps

The grouped queue of what is missing from the planned-work read model: unestimated, unscheduled, unteamed and unaligned work, teams mixing estimate units, and source work whose binding has stopped converging. Each group names why it changes the calculation and where to fix it.

• teamIds?: string[] | string — Telos team UUIDs to scope the read to; omit for every team
• cycleId?: uuid — Cycle UUID as the planning window
• jiraSprintId?: uuid — Jira sprint UUID as the planning window
• start?: string — Planning window start (YYYY-MM-DD)
• end?: string — Planning window end, exclusive (YYYY-MM-DD)

get_task_planned_work_drift

Compare one cycle's or Jira sprint's frozen opening plan with the live planned-work collector. Returns unit-preserving distributions, frozen and current coverage, exact addition/removal/change counts, and up to 100 deterministic item details per change kind; estimate origins distinguish explicit values from workspace-default assumptions, and a missing opening baseline is never reconstructed. Arbitrary date ranges remain current-only through planned-work-summary.

• teamIds?: string[] | string — Telos team UUIDs to scope the read to; omit for every team
• cycleId?: uuid — Cycle UUID as the frozen planning window
• jiraSprintId?: uuid — Jira sprint UUID as the planning window

list_task_statuses

List the workspace's concrete task statuses in stable lifecycle and custom position order.

• includeArchived?: boolean | "true" | "false" — Boolean
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_tasks

List tasks with cursor pagination. Optionally filter by opportunity, stable lifecycle status, concrete statusId, priority, team, owner, or to work that no cycle holds yet.

• opportunityId?: uuid — Opportunity UUID filter
• status?: "backlog" | "todo" | "in_progress" | "completed" | "cancelled" | "duplicate" — Task status filter
• statusId?: uuid — Concrete workspace status UUID filter
• priority?: "low" | "medium" | "high" | "urgent" — Task priority filter
• teamId?: uuid — Team UUID filter
• ownerUserId?: uuid — Owner UUID filter. Pass your own user id (whoami) for 'my assignments'
• noCycle?: boolean | "true" | "false" — Only work bound to no cycle: the pool a cycle is planned from
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_task

Get a specific task by id.

• id: uuid — Task UUID

list_task_development_updates

List development updates posted on this task.

• id: uuid — Task UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

count_tasks_by_status

True totals for the six stable lifecycle status types under the same filters `list` takes. Custom named statuses deliberately roll up to their parent type, preserving the aggregate answer to 'how much work is in flight'.

• opportunityId?: uuid — Opportunity UUID filter
• priority?: "low" | "medium" | "high" | "urgent" — Task priority filter
• teamId?: uuid — Team UUID filter
• ownerUserId?: uuid — Owner UUID filter

get_task_time_in_status

Wall-clock totals per workflow status, folded from the task's status-transition ledger. One row per concrete status the task has visited (named custom statuses stay distinct; rows with no resolvable status fall back to the lifecycle type), with `current` marking the status still accruing. Imported history is only as complete as the source provided.

• id: uuid — Task UUID

get_task_context

Get everything needed to act on a task in one call: the task spec, its parent opportunity and PRD, the customer(s), comments, linked insights, the active template step, and any linked PRs. Sections you lack the read capability for (e.g. the parent opportunity, customers, insights) come back null. Pass the task ref (e.g. TF-24).

• ref: string — Task ref, e.g. TF-24

list_recurring_tasks

List recurring-task definitions with cursor pagination: each one's schedule (human-readable cadence + next occurrence), team, owner, and template. These are the definitions a background sweep materializes into real tasks; use list to see the tasks they produced.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_recurring_task

Get a recurring-task definition by id: the stored row (rrule, template, active flag). The human-readable cadence, next occurrence, team and owner are list-only.

• id: uuid — Recurring-task definition UUID

get_external_links

Everything outside Telos attached to one work item, in a single read: `refs` are the outbound links (pull requests, issues, Slack threads, Notion pages, linked Telos chat messages) and `blockers` are the open 'waiting on someone outside the team' flags. Blockers exist for tasks and opportunities only, so an insight always answers with an empty list. Links to messages in rooms you cannot read are filtered out, and every message URL is rebuilt from the room's current slug. Reading an opportunity's or insight's links also requires that entity's read permission, not just task:read.

• entityType: "task" | "opportunity" | "insight" — Work item type the link hangs off
• entityId: uuid — Work item UUID

list_agent_runs

Coding-agent dispatch history with cursor pagination, newest first. Supply exactly one of taskId (one task's runs, with the repo and branch the agent worked in) or integrationId (one connector's runs, with each run's task ref). The field the other filter would have told you comes back null.

• taskId?: uuid — List one task's runs
• integrationId?: uuid — List one integration's runs
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_cycle_allocation

Explicit task estimates grouped by category and evenly split across linked objectives and distinct task-linked customers (insights and onboarding pins). Open cycles return live leaf work and the current goal revision. Completed cycles return frozen close-time shares and the goal revision in effect at cycle end, or state unavailable when no snapshot exists. Missing estimates are counted, never imputed; up to 500 rows per axis with full denominators. No spent time or salaries. Requires task, opportunity, objective, category, customer and insight read access too.

• id: uuid

list_cycles

List the organisation's retained cycle windows with cursor pagination. Reading never generates new windows.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_cycle

Get one cycle window and its lifecycle state.

• id: uuid — Cycle UUID

get_cycle_grids

List the grids cycles are generated on: one row for the organisation in org mode, or one row per cycle-enabled team in team mode. Answers which teamId every other cycle read should be narrowed by.

list_cycles_with_stats

List one grid's cycle windows newest first, each decorated with derived delivery analytics: lifecycle status, capacity and committed days, scope, work added after start, work spilled out, work completed, success percentage, and the customer commitments falling due inside the window. Closed cycles read their frozen close-time digest, open ones read live bindings.

• teamId?: uuid | null — Team UUID of the grid to read; omit for the organisation grid
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_cycle_by_number

Resolve the cycle a grid numbers as N, the addressing the /cycles/{grid}/{number} deep links use. The grid is a team slug, or the literal 'org' for the organisation grid. Answers with the cycle plus its team slug and derived lifecycle status.

• grid: string — Team slug of the grid, or 'org' for the organisation grid
• number: integer | string — The cycle's number within that grid

get_cycle_burnup

Get the daily cumulative scope and completed series across a cycle's window, in estimate days. Scope rises as work is bound after the start; completions land on their completion day, with post-window completions clamped onto the final point. Closed cycles read their frozen close-time digest.

• id: uuid — Cycle UUID

get_cycle_breakdown

Group a cycle's member work by owner, by priority and by team, each with a count and a percentage of the cycle's scope. The composition summary; ask task list with a cycle filter for the rows themselves.

• id: uuid — Cycle UUID

get_cycle_options

A bounded, searchable window over every retained cycle, grouped by grid and newest window first, for building a cycle selector. Matches name or number, and narrows to the grids of the given teams. The answer carries the total for that scope, so a caller can tell a partial window from a complete one, and any cycle asked for by includeIds rides in a separate `included` array so it cannot disguise a truncated window as a complete one; cycle list is the paginated read that walks them all.

• q?: string — Match against the cycle name or number
• limit?: integer | string — Window size (default 100, max 100)
• teamIds?: string[] | string — Team UUIDs whose grids to search; organisation-grid cycles stay in every scope. Omit for every grid
• includeIds?: string[] | string — Cycle UUIDs to return even when the scope or the window excludes them, so an existing selection keeps its label. They answer in `included`, beside the window rather than inside it

get_cycle_impact_candidates

The active and future cycles of every enabled grid, current window first: the only windows a task may be assigned to. Narrow by teamId to one task's effective grid. Retained history is excluded by design and never displaces these rows.

• teamId?: uuid | null | string — Narrow to one team's grid; null (the literal string "null" on a query string or CLI flag) for work with no effective team, omit for every enabled grid
• limit?: integer | string — Window size (default 100, max 200)

get_cycle_verdict

Get the immutable close-time verdict for a committed cycle, if it has closed.

• id: uuid — Cycle UUID

get_cycle_config

Get the organisation's cycle-planning configuration. Null means it has never been configured.

get_cycle_commitments

List the customer promises falling due inside a cycle's window, attributed to its grid, with delivery coverage: delivered, covered, at risk (with breach days), or uncovered.

• id: uuid — Cycle UUID

get_cycle_commitments_batch

Read the customer promises of up to twenty cycle windows in one call, each answering exactly what cycle commitments answers for that window: the promises falling due inside it, attributed to its grid, with delivery coverage. Ids outside the organisation are dropped rather than reported. For a planning horizon of cycle columns; ask cycle commitments for one window.

• ids: string[] | string — Cycle UUIDs, comma-separated on a query string or CLI flag (1 to 20)

get_cycle_load

Break a cycle's live leaf work down by owner as assignedMinutes against capacityMinutes available for this cycle: one workday per weekday minus otherCycleMinutes, floored at zero. Other overlapping cycles block their full estimate, even with mismatched dates; touching end dates do not overlap. Unestimated work uses the organisation default; completed work counts and unowned/non-human work is separate. Team membership supplies idle rows, not a separate capacity pool or visibility role. Every human carrying work here or elsewhere gets a row; only the idle tail is capped at 25 with idleOmitted. Top-level assignedMinutes and capacityMinutes include the full roster before that cap.

• id: uuid — Cycle UUID

get_cycle_load_batch

Read the per-person load of up to twenty cycle windows in one call, with the same remaining capacity and complete roster totals as cycle load. Every other overlapping cycle blocks its full estimated load, including cycles outside this batch; mismatched dates are not prorated. Ids outside the organisation are dropped rather than reported. These are alternative planning views of shared people, not additive team capacity pools.

• ids: string[] | string — Cycle UUIDs, comma-separated on a query string or CLI flag (1 to 20)

get_cycle_events

List the cycle's informational ledger, newest first: scope added after start, promises at risk on entry, promises moved out, and promises unfinished at close.

• id: uuid — Cycle UUID
• cursor?: uuid
• limit?: integer | string

get_cycle_impact

Preview the selected cycle's standing commitments, rollover effects, and cross-team collisions without mutating work.

• id: uuid — Cycle UUID
• taskId?: uuid

get_allocation_actual

Shares of saved work in a calendar month, grouped by category, objective or team. Excludes time away; multi-objective work splits evenly. Filters follow the work's team. Returns up to 500 groups with the complete count and denominator, never estimates or individual identities. Requires organization-wide cost and underlying resource read access.

• month: string
• teamIds?: string[] | string
• axis: "category" | "objective" | "team"

get_allocation_actual_work

Work-item breakdown for one category, objective or team in the recorded monthly allocation. Pass key null (the string null in REST/CLI) for unclassified work. Returns up to 200 items with the complete count and denominator; shares are within this group, not the whole company. Uses the same authority, tenant and read-access rules as the summary.

• month: string
• teamIds?: string[] | string
• axis: "category" | "objective" | "team"
• key: uuid | null | string

get_allocation_review

Get the latest immutable proposal or confirmation for the authenticated engineer's ISO week. This personal read never accepts another user id.

• periodStart: string — ISO-week Monday (YYYY-MM-DD)

get_allocation_capacity

The org's members with the employment FTE and team split in force on a day, the defaults applied where no row exists, and which members belong to more than one team with no split at all. Percentages are basis points; 10000 is one whole person.

• teamId?: uuid — Telos team UUID to scope the read to
• asOf?: string — Day the periods are read at (YYYY-MM-DD); defaults to today

list_allocation_jira_sprints

Every Jira sprint this workspace has discovered, newest start first, with its board, provider id, state and half-open dates. A sprint with no dates is listed but is not a planning window: nothing defaults one for it. Pass a sprint's id as `jiraSprintId` to the planned-work reads to plan in it.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_allocation_planned_capacity

Team and organization capacity for a cycle, a Jira sprint, a date window or a month or quarter range, in person-weeks: employment FTE times team share times the days of the window. Capacity is distributed by estimate coverage and axis share, with the uncovered remainder, the share no team claims and the days no planning window covers reported as their own buckets. Raw estimate totals never cross a team or a window; only person-weeks do.

• teamIds?: string[] | string — Telos team UUIDs to scope the read to; omit for every team
• cycleId?: uuid — Cycle UUID as the planning window
• jiraSprintId?: uuid — Jira sprint UUID as the planning window
• start?: string — Planning window start (YYYY-MM-DD)
• end?: string — Planning window end, exclusive (YYYY-MM-DD)
• rangeStart?: string — Month or quarter range start (YYYY-MM-DD)
• rangeEnd?: string — Month or quarter range end, exclusive (YYYY-MM-DD)

get_allocation_goal

Read the standing objective and category percentage benchmarks. Pass revision for an immutable saved version with its original labels and effective timestamp; omit for today's goal and live catalogs. Requires objective and category read access too. Null targets are unset; zero is explicit. Each live catalog is capped at 500 items with a total count, prioritizing saved targets; removed saved items remain visible.

• revision?: integer | string — Read an immutable saved revision instead of the current goal and live catalog

export_observed_evidence

Every marker, session, usage segment and allocation one member submitted inside a period, as JSON. The subject defaults to the caller, who always reads their own; any other subject is part of the allocation surface and needs allocation:read.

• subjectUserId?: uuid — Member whose evidence to read; defaults to the caller
• periodStart: string — First day of the window (YYYY-MM-DD)
• periodEnd: string — Last day of the window (YYYY-MM-DD)

list_insights

List customer insights (the customer-voice evidence layer). Filters compose: lifecycle status, demand root (customer), linked work (opportunity/task/objective), review team, recorder, tag, and full-text search over the verbatim. Archived insights are hidden unless includeArchived is set.

• status?: "created" | "review" | "need_context" | "active" | "rejected" | "delivered" | "stale" — Insight lifecycle status filter
• customerId?: uuid — Customer UUID filter
• opportunityId?: uuid — Only insights linked to this opportunity
• taskId?: uuid — Only insights linked to this task
• objectiveId?: uuid — Only insights linked to this objective
• reviewTeamId?: uuid — Only insights routed to this team's review queue
• recordedByUserId?: uuid — Only insights recorded by this user (whoami for your own)
• tagId?: uuid — Only insights carrying this tag
• search?: string — Full-text match on the verbatim
• includeArchived?: boolean | "true" | "false" — Include archived insights (default false)
• reviewQueue?: boolean | "true" | "false" — Your own review queue: insights routed to teams you are the insight reviewer for, plus your own insights sent back for context. Replaces the other filters when set.
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_insight

Get an insight with its demand root, links, tags, and committed impacts.

• id: uuid — Insight UUID

list_blocking_insights

The client-voiced blockers on one opportunity or task: open insights whose link to it is flagged blocking. Use it before promising a delivery date.

• itemKind: "opportunity" | "task" — The work item's kind
• itemId: uuid — The work item's UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_similar_insight_signals

Embedding-similarity signals for one insight: near-duplicate insights the org already holds, and near-duplicate asks it already REJECTED (with the reason, the category, and who said no). No LLM call. Read this before recording or reviewing a signal so the org does not relitigate a decision it already made.

• id: uuid — Insight UUID

get_insight_patterns

The pattern board: semantic clusters of open insights that a human-triggered judge has already scored against the vision, strategies and objectives, plus the raw similarity graph (nodes and edges) behind them. `enabled` and `embeddingModelConfigured` tell you whether clustering is running at all; `unjudgedCount` is how many current clusters have no verdict yet; `truncated` means more open insights exist than the newest window considered.

list_external_stakeholders

List the org's other stakeholders (named demand voices with no Telos seat), alphabetically, each with how many insights it roots. Use one's id as externalStakeholderId when recording an insight. Returns at most 500; an org past that needs the in-app directory.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_tags

List every tag alphabetically with usage counts so you can cluster insights onto existing tags instead of minting duplicates. Follow nextCursor until hasMore is false.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_tag_themes

List the themes tags can be grouped under, with the colour each theme lends its tags.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_customers

List customers with cursor pagination. Optionally filter by status.

• status?: "prospect" | "onboarding" | "pilot" | "live" | "churned" | "lost" — Customer status filter
• ownerId?: uuid — Owner (DRI) user UUID filter; pair with whoami to list your own accounts
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_customer

Get a customer by UUID or by ref (e.g. CUS-12).

• id: string — Customer UUID or ref (e.g. CUS-12)

list_customer_contacts

List the named people on a customer account, primary contact first, then newest. Use a contact's id to attribute an insight to the person who said it.

• id: uuid — Customer UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_customer_opportunities

The opportunities tied to this account, most-active first. `stepInstanceId` is the onboarding milestone the link is pinned to (null when unpinned).

• id: uuid — Customer UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_customer_updates

The account's update stream, newest first: notes posted on the customer plus progress posted on any opportunity the account reaches (linked or through its insights).

• id: uuid — Customer UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_customer_commitments

Every dated promise made to a client across the org (an open insight carrying a deadline), soonest first so overdue leads, resolved to the work delivering it. `atRisk` flags a near deadline with nothing in flight.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_customer_arr_history

The account's ARR level series oldest first: each point is 'ARR was this much from this date'. Deltas are derived between consecutive points, never stored.

• id: uuid — Customer UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_customer_arr_summary

The portfolio view of revenue in one call: `stats` totals ARR and account count per lifecycle position (live, pilot, onboarding, prospect), and `waterfall` gives ARR gained/lost/net per month over the requested window, derived from the same level series.

• months?: integer | string — Waterfall window in months (1-24, default 6)

list_customer_reviews

The account's pre-meeting reviews, newest first: what the client had going on in each stored date window. Summaries only; read one with get_customer_review.

• id: uuid — Customer UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_customer_review

One stored review in full: the digest (new asks, shipped work, updates, overdue commitments, delayed work, stuck asks) plus the generated narrative when there is one.

• id: uuid — Customer UUID
• reviewId: uuid — Review UUID

get_customer_onboarding

The account's onboarding in one call: every milestone in order with the active one flagged, the ARR tranche each unlocks, and the work sitting on it (opportunities pinned to the milestone plus bespoke tasks). `hasOnboarding` is false when the account was never started.

• id: uuid — Customer UUID

list_teams

List teams in the organisation, with cursor pagination.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_team

Get one team: its name, description, ref prefix (the task-ref namespace, e.g. ENG-42) and default PRD template. The roster is a separate read (list_team_members).

• id: uuid — Team UUID

list_team_members

The team's roster with cursor pagination: each member's user id, name, email, avatar, membership id, and org role. Salary and weekly-hours fields are included only for a caller holding compensation:read over this team, and are absent otherwise rather than null. Requires team:read.

• id: uuid — Team UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_team_ownership_configs

Who owns insight review for each team. One row per team, optionally narrowed to one team; teams with nobody assigned come back with a null reviewer.

• teamId?: uuid — Only this team's row
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_users

List org members with cursor pagination.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_user

Get one org member's profile: name, email, avatar, org role and weekly hours. Salary fields are included only for a caller holding compensation:read, and are absent otherwise rather than null. Use whoami for the key's own user.

• id: uuid — User UUID

list_roles

The org's roles with the permission grants each one confers, so you can see who can do what before proposing a change. Creating, renaming, deleting a role and rewriting its grants are in-app only.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_rooms

List rooms with cursor pagination. Scope 'mine' (default) returns the rooms you are a member of (DMs, group channels, system rooms) with unread counts and your per-room state, most recently active first. Scope 'open' returns every live open group channel in the org — the channel browser — with isSubscribed telling you which ones you are already in; the per-membership fields are null on those rows. Archived channels appear in neither scope.

• scope?: "mine" | "open" — 'mine' (default) for your rooms, 'open' for joinable open channels
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_room

Get a room by UUID with your membership role. Members always read; any org user reads an open group channel; a private group, DM, or system room without a membership row is forbidden.

• id: uuid — Room UUID

list_room_members

List the members of a room you can read, oldest join first, with each member's room role. Requires read access to the room (member, or any org user for an open group channel).

• id: uuid — Room UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_messages

List a room's top-level messages, newest first, with cursor pagination (service-capped at 100 per page). Rows carry author, reactions, attachments, and thread reply counts; fetch a thread's replies with the thread action. Requires read access to the room (member, or any org user for an open group channel).

• roomId: uuid — Room UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_message_thread

List the replies threaded under a top-level message, newest first, with cursor pagination. Requires read access to the message's room.

• id: uuid — Message UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_pinned_messages

List pinned messages, most recently pinned first, with cursor pagination. Pass roomId to scope to one room you can read; omit it for every pin across the rooms you are a member of. Rows are message rows — read the room's name with get_room.

• roomId?: uuid — Scope to a single room
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

search_messages

Search the rooms you are a member of by message body (case-insensitive substring), newest first, with an optional room, author, DM-counterpart, and date filters. Returns the top 40 matches with a snippet around the hit; it is a search, not a paginated list, so narrow with filters rather than paging. A query under two characters needs at least one filter to anchor on.

• q?: string — Text to find in message bodies (min 2 chars to match on its own)
• roomId?: uuid — Scope to a single room
• fromUserId?: uuid — Only messages by this author
• toUserId?: uuid — Only messages in the DM with this user
• fromDate?: string — Only messages at or after this time
• toDate?: string — Only messages at or before this time

list_comments

List a discussion thread, newest first, with cursor pagination. Pass entityType and entityId for an entity's top-level comments, or parentId for the replies threaded under one comment. Rows carry the author, reaction aggregate, and (for top-level rows) the reply count.

• entityType?: "direction_document" | "vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle" — Entity the comments hang off (with entityId)
• entityId?: uuid — Entity UUID (with entityType)
• parentId?: uuid — Read this top-level comment's thread replies instead
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_files

List file metadata with cursor pagination. Pass entityType AND entityId together for one entity's attachments (oldest first); omit both for the org-wide manifest (newest first). Bytes never travel this API — `get` returns a short-lived presigned download URL. Rides file:manage because the unfiltered form is the same org manifest the in-app admin surface gates on it.

• entityType?: "direction_document" | "vision" | "objective" | "metric" | "opportunity" | "task" | "team" | "user" | "task_assignment" | "webhook_subscription" | "template" | "template_step" | "template_step_instance" | "template_checklist_instance" | "strategy" | "strategy_version" | "vision_version" | "notification" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "opportunity_risk" | "file" | "tag" | "tag_theme" | "prd_template" | "room" | "message" | "comment_thread" | "time_entry" | "org" | "scoring_criterion" | "cycle" — Attachment target entity type; requires entityId
• entityId?: uuid — Attachment target UUID; requires entityType
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_file

Get one file's metadata. Once the upload has been scanned and processed (status `clean`) the response carries `downloadUrl`, a presigned GET valid for about 15 minutes; while the file is pending, processing, or failed that field is null and `status` / `processingError` say why.

• id: uuid — File UUID

get_file_storage_usage

Bytes currently held against the org's storage quota, the quota itself, and the percentage used. Check this before a large upload: request-upload refuses anything that would cross the quota.

list_templates

List the org's template templates with cursor pagination. Templates carry no category: categories group tasks and opportunities, not templates.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_template

Get a template template with its ordered steps. The terminal Completed/Cancelled pair is system-managed and not included.

• id: uuid — Template UUID

get_template_usage

The tasks and opportunities currently running on this template, with counts. Delete refuses while either count is above zero; reassign-and-delete is the way through.

• id: uuid — Template UUID

get_default_template

The template a new task, opportunity or customer gets when the caller does not choose one: the flagged default, else the oldest matching template. 404 when the org has none for that entity type.

• entityType: "task" | "opportunity" | "customer" — Entity the template runs on

get_template_instance

The live process on a task, opportunity or customer: which step is active, how far it has run, and every step instance in order with its owner and status. This is the read an agent needs before advancing a step or writing a handoff. 404 when the entity carries no template.

• entityType: "task" | "opportunity" | "customer"
• entityId: uuid

list_categories

List the org's categories in display order (used to group templates and to classify time entries).

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_category

Get one category: its label, slug, color and sort order. Categories group tasks and opportunities and classify time entries; the system Bug and Incident categories are present in every org.

• id: uuid — Category UUID

list_prd_templates

List the PRD templates visible to the key's user: shared (org-wide) templates plus those owned by the user's teams. Pass allTeams to read the whole org catalog instead, which additionally requires prd_template:update.

• allTeams?: boolean | "true" | "false" — Return every template in the org, including other teams' (requires prd_template:update)
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_prd_template

Get one PRD template: its name, markdown content, and team scope (teamId null means shared org-wide). Visible when the template is shared or owned by one of the key user's teams. Writing it into an opportunity is apply_opportunity_prd_template.

• id: uuid — PRD template UUID

list_time_entries

List time entries in a date range (from/to, max 366 days), newest first, with cursor pagination. Defaults to the authenticated user's own entries. engineerId reads another engineer's entries and requires the salary read permission (compensation:read); a team-scoped grant admits only engineers on the caller's teams.

• from: string — Range start (YYYY-MM-DD, inclusive)
• to: string — Range end (YYYY-MM-DD, inclusive; max 366 days after from)
• engineerId?: uuid — Another engineer's user UUID; requires compensation:read
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

aggregate_time_entries_by_category

Total hours in a date range bucketed by category, across all engineers in the org (optionally filtered to one team's members). Cost reporting: requires an org-wide cost:read grant.

• from: string — Range start (YYYY-MM-DD, inclusive)
• to: string — Range end (YYYY-MM-DD, inclusive; max 366 days after from)
• teamId?: uuid — Restrict to one team's members

get_time_entry_costs_for_range

Hydrated time entries for every engineer in a date range (hours, derived cost, engineer, category, target), capped at 5000 rows; `truncated` flags the cap. Not a paginated list: it is one capped snapshot of the whole window, so narrow the range rather than paging. Use list_time_entries to walk your own entries with a cursor. Cost reporting: requires an org-wide cost:read grant.

• from: string — Range start (YYYY-MM-DD, inclusive)
• to: string — Range end (YYYY-MM-DD, inclusive; max 366 days after from)
• teamId?: uuid — Restrict to one team's members

get_time_entry_cost_for_opportunity

Sum of hours times each entry's snapshotted hourly rate for every time entry logged against the opportunity. Returns 0 when nothing is logged. Requires an org-wide cost:read grant.

• opportunityId: uuid — Opportunity UUID

get_time_entry_cost_for_task

Sum of hours times each entry's snapshotted hourly rate for every time entry logged against the task. Returns 0 when nothing is logged. Requires an org-wide cost:read grant.

• taskId: uuid — Task UUID

list_time_entries_for_opportunity

Every entry logged against one opportunity, newest first: date, hours, and note. Hours only — the cost of those hours rides cost:read on get_time_entry_cost_for_opportunity. Who logged each entry is individual-grain time, so engineerId/engineerName come back null unless the caller holds compensation:read (which an API key never does): sum the hours, do not attribute them.

• opportunityId: uuid — Opportunity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_activities

The activity log for one entity, newest first, with cursor pagination: who changed which field, from what to what, and when. Requires the read capability of the entity you are asking about. Read it before proposing a change so you know what already happened.

• entityType: "opportunity" | "task" | "customer" | "insight" — Entity type. One of: opportunity, task, customer, insight
• entityId: uuid — Entity UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_subscription

Report whether the authenticated user currently follows an entity, i.e. receives its notifications. False covers both never-subscribed and explicitly muted.

• entityType: "opportunity" | "task" | "comment" | "customer" | "customer_update" | "customer_document" | "insight" | "direction_document" | "vision" | "strategy" | "objective" | "metric" | "team" | "template" | "opportunity_risk" | "file" — Entity to follow. One of: opportunity, task, comment, customer, customer_update, customer_document, insight, direction_document, vision, strategy, objective, metric, team, template, opportunity_risk, file
• entityId: uuid — Entity UUID

list_notifications

List the authenticated user's notifications, newest first, with cursor pagination. Filter to unread only, pinned only, or a set of notification types.

• unreadOnly?: boolean | "true" | "false" — Only return unread notifications
• pinnedOnly?: boolean | "true" | "false" — Only return pinned notifications
• types?: string[] | string — Only return these notification types. JSON array on MCP, comma-separated on REST and CLI. One of: strategy.published, strategy.updated, vision.published, direction.commented, customer.update_posted, customer.went_live, insight.assigned, insight.needs_context, insight.rejected, opportunity.completed, opportunity.cancelled, objective.committed_date_breach, cycle.scope_changed, template.step_assigned, task.handoff, task.agent_run_completed, task.agent_run_failed, task.agent_run_cancelled, comment.mention, comment.thread_reply, doc.mention, room.invited, room.mentioned, community.mentioned, good_vibes.shoutout
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

count_unread_notifications

Count the authenticated user's unread notifications.

list_webhook_subscriptions

List the org's outbound webhook subscriptions. Secrets are write-once and never returned.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_integrations

List the org's installed integrations: connector type, name, status, health counters, and the non-secret config (watched channels, repo maps). Stored credentials are never returned. Import-only sources are excluded, matching the in-app directory.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_integration

Get one integration's connector type, name, status, health counters, and non-secret config. Stored credentials are never returned.

• id: uuid — Integration UUID

list_integration_events

The integration's inbound/outbound delivery ledger with cursor pagination, newest first: kind, status, dedup key, attempt count, error text, and timings. The raw third-party payload and request headers are deliberately withheld — they carry provider verification tokens and signature headers.

• status?: "received" | "processing" | "succeeded" | "failed" | "skipped_duplicate"
• kind?: "webhook" | "command" | "interaction" | "poll" | "outbound" | "backfill"
• id: uuid — Integration UUID
• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

list_import_runs

The org's bulk-import runs (Linear, Jira, CSV) with cursor pagination, newest first: source, status (pending/running/paused/completed/partial/failed), per-phase counts, error text, and timings. Starting a run is in-app only; use this to find the run to watch.

• cursor?: string — Opaque pagination cursor from a previous page's nextCursor
• limit?: integer — Items per page (default 50, max 200)

get_import_run

One import run's durable row: source, status, the sanitized run plan, accumulated per-phase counts, resume checkpoint, error text, and timings. Poll it to watch a run progress; a status of completed, partial, or failed is terminal.

• id: uuid — Import run UUID