search_goals

Beschreibung

Listet die Ziele auf dem Pipeline-Board — standardmäßig in manueller Board-Reihenfolge. Lässt sich nach Titeltext, Verantwortlichem, Phase, Konfidenz, Abschlusszeitraum und Änderungszeitraum filtern — auch kombiniert — und liefert Kurzfassungen; Details holst Du mit get_goal. Für einen Blick in die abgeschlossene Historie (z. B. als Grundlage für eine Aufwandsschätzung) nutzt Du orderBy: "completion" mit completedAfter/completedBefore und blätterst weiter, indem Du den Wert aus dem Feld nextCursor der Antwort als Parameter cursor zurückgibst. Bei orderBy: "completion" gilt: Hör beim ersten Ziel ohne Abschlussdatum auf — ab da ist kein Abschlussdatum erfasst, die Sortierung kann diese Ziele also nicht einordnen. Das heißt NICHT “nicht abgeschlossen”: ein abgeschlossenes Ziel, dessen Datum nie erfasst wurde, landet ebenfalls dort. Um abgeschlossene Ziele unabhängig von einem erfassten Datum aufzulisten, nutzt Du stage: ["done","reflect"]. Zeilen mit erfasstem Abschlussdatum tragen completedAt und completedAtSource, Zeilen ohne tragen keines von beiden. Prüfe completedAtSource, bevor Du einem Datum vertraust: stage_change ist exakt, change_event kann zu FRÜH liegen, und updated_at ist lediglich der Zeitpunkt der letzten Änderung — eine Näherung, KEIN echtes Abschlussdatum. Wichtig: updatedAfter/updatedBefore und die Recency-Sortierung beziehen sich auf die letzte Änderung, nicht auf einen Abschlusszeitpunkt — dafür sind completedAfter/completedBefore und orderBy: "completion" da. Das Feld effort ist hier die vom Verantwortlichen geplante Größe (ein Näherungswert eines einzelnen Schätzers), nicht der Ist-Aufwand: den tatsächlichen Aufwand (effort.actual.mean, über mehrere Schätzer gemittelt) liest Du über get_goal. Mit includeDescription bekommst Du zusätzlich eine gekürzte Vorschau der Beschreibung je Ziel, damit ein Vergleichsziel-Read für eine Aufwandsschätzung in einem Aufruf gelingt.

Beschreibung für das Modell

Diesen Text sieht das KI-Modell — unverändert und auf Englisch, so wie ihn der Server ausliefert:

List goals on the pipeline board for the connected organization. Filter by title text, owner, confidence (0–100), pipeline stage, a completion window (completedAfter/completedBefore, ISO 8601, half-open) and/or a last-updated window (updatedAfter/updatedBefore, same shape) — all combinable, so “goals owned by X in WIP” is one call. Stage takes an array of the canonical names: ideation, scoped, rated, next, wip, blocked, reflect, done, declined ([“done”,“reflect”] is completed work). Returns goal summaries (stage, owner, effort, confidence, budget, category, updatedAt, and completedAt/completedAtSource where a completion date is recorded). Server-capped at 50 rows; a note marks truncation, and total is always the exact number of goals matching the filters (independent of the page) — for a count or a per-stage breakdown alone, call count_goals instead.

The effort field here is the goal owner’s single PLANNED t-shirt size on the ordered Fibonacci scale S < M < L < XL < XXL (call get_guidance for the numeric mapping) — a proxy, NOT the actual effort and NOT a multi-estimator aggregate. For what a comparable goal actually cost, read effort.actual.mean via get_goal. Set includeDescription: true to also return a truncated description preview per row, so a done-history comparables read reaches the narrative in one call.

Ordering defaults to manual board position, which is meaningless for completed work: a truncated board-ordered list is an arbitrary slice, not the latest. For a DONE-HISTORY read (e.g. estimating a new goal’s effort from past work) pass orderBy: “completion” and narrow with completedAfter/completedBefore when you want one period. A completion window does NOT change the ordering on its own, so pass both — a windowed read left in the default board order is still an arbitrary slice. To read beyond the first page, take the nextCursor value from the response and pass it back as the cursor argument, keeping every other argument identical — changing a filter invalidates the cursor. The cursor carries the ordering its walk started with and fixes the page size, so either omit orderBy or pass the same one, and start a new read without a cursor to use a different page size. A full history read may take several sequential calls.

Under orderBy: “completion”, stop at the first goal with no completion date: nothing beyond that point has a recorded completion date, so the ordering cannot rank it. That is not the same as “not completed” — a completed goal whose date was never recorded sorts there too. To list completed goals regardless of whether a date was recorded, use stage: [“done”,“reflect”]. Setting either completion bound also restricts the result to completed goals. Read completedAtSource before trusting a date: “stage_change” is exact, “change_event” may be early, and “updated_at” is only the record’s last-modified time — an approximation, NOT a true completion date. A goal with no completedAt has no completion date recorded; that is not evidence it is uncompleted.

IMPORTANT: updatedAfter/updatedBefore and the “recency” order are based on when a goal was LAST UPDATED, not when it was completed — use completedAfter/completedBefore and orderBy: “completion” for real completion dates. Do not present the “recency” ordering as a completion sequence. Use get_goal for full detail.

Parameter

Name	Typ	Pflicht	Einschränkungen	Beschreibung
query	Text	Nein		Case-insensitive substring match on the goal title
ownerId	Text	Nein		Restrict to goals owned by this user id
confidenceGt	Ganzzahl	Nein	0–100	Only goals with confidence greater than this (0–100)
confidenceLt	Ganzzahl	Nein	0–100	Only goals with confidence less than this (0–100)
stage	Liste	Nein	ideation | scoped | rated | next | wip | blocked | reflect | done | declined, mind. 1 Eintrag	Restrict to these pipeline stages (one or more of: ideation, scoped, rated, next, wip, blocked, reflect, done, declined). Always an array, e.g. [“wip”], or [“done”, “reflect”] for completed work.
updatedAfter	Text	Nein		Only goals last updated at or after this ISO 8601 timestamp. This is the LAST-UPDATE time, not a completion date.
updatedBefore	Text	Nein		Only goals last updated strictly before this ISO 8601 timestamp. Combined with updatedAfter this is a half-open window, so adjacent periods tile cleanly.
completedAfter	Text	Nein		Only goals COMPLETED at or after this ISO 8601 timestamp. This is a real completion date, unlike updatedAfter. Setting it also restricts the result to completed goals (stage done/reflect).
completedBefore	Text	Nein		Only goals COMPLETED strictly before this ISO 8601 timestamp. Combined with completedAfter this is a half-open window, so adjacent periods tile cleanly. Setting it also restricts the result to completed goals (stage done/reflect).
orderBy	Text	Nein	position | recency | completion	’position’ (default) is manual board order; ‘completion’ is most-recently-completed first and is the ordering to use for a done-history read; ‘recency’ is most-recently-updated first, which answers what was last TOUCHED.
cursor	Text	Nein		Opaque cursor from a previous response’s nextCursor field, to fetch the next page. It carries the ordering the walk started with and fixes the page size, so either omit orderBy or pass the same one; passing the other paged ordering is rejected. Keep the other arguments identical.
limit	Ganzzahl	Nein	1–50	Max rows (capped at 50). Ignored when a cursor is passed — the cursor carries the page size the walk started with.
includeDescription	Wahrheitswert	Nein		Include a truncated preview (first 160 chars, marked with an ellipsis when cut) of each goal’s description. Off by default. Use it for a done-history comparables read so the narrative reaches you in one call instead of one get_goal per goal. Note this description is the goal’s own text; the actual completed effort (effort.actual.mean) still comes from get_goal.

Zurück zur Übersicht