Skip to main content
Code-shipped tool sets ship with the platform, each annotated with governance metadata. Each row in the table is one code-shipped tool set. Database-defined tool sets (Google Workspace, external HTTP integrations, MCP plugins) live in the toolSets table and are not enumerated here — see /platform/tools in the Forge Console for the live catalog. For the conceptual frame — register, audit, publish, invoke — see Tool Registry.

Code tool sets

The registry changes as platform agents gain or retire capabilities. TOOL_SETS and TOOL_SET_MEMBERS are the source of truth; the Console’s Platform → Tools page is the live operator catalog. Dispatch-injected tools are deliberately absent from both static and workspace sets.

Database-defined tool sets

The following families are declared in TOOL_SET_MEMBERS (for governance metadata) but their tools are seeded as rows in toolDefinitions with a runtime type of http_api, mcp_remote, or mcp_convex. They appear on /platform/tools once the corresponding seeder runs. Twelve Google Workspace splits, plus per-vendor MCP and HTTP integrations seeded from vendor manifests. The full live catalog — code-shipped + DB-defined + factory-bound — is the operator surface at Platform → Tools.

Factory-bound tools

These tools have boundAtDispatch: true in TOOL_META. They are constructed per-dispatch by a factory function (so their Zod input schema lives on the factory output, not on a static singleton) and surfaced in the catalog with a “Bound at dispatch” indicator. This table is the complete set of dispatch-injected tools; getFile and putFile remain as deprecated aliases of file_get and file_put. Agent authors do not add any of these names to a tool set; the dispatch context decides whether a concrete, bound tool is available. Every workflow node agent, chat agent, Factory Manager and the Workflow Architect receives knowledge_search. No tool set has to grant it; it is a dispatch-injected tool. The Workflow Architect searches global, company, its draft’s channel and its own agent:workflow-author knowledge, and can still call it while a plan proposal waits for confirmation. Its hits carry no citation ref. Without scopes, Forge resolves the scopes from where the agent runs: global, company, the agent’s own agent: and team: namespaces, and the factory, project and channel of the run or session. The search goes through the knowledge capability. Fresh search reads the synchronized Knowledge store only. The tool returns { found: true, hits }. Each hit carries entryId, namespace, score, contentType, grade and text, best first, and similarity (the cosine) when vector search found it. A hit with revisionOf is a pending revision: a proposed rewrite of the proven case that revisionOf names, which has not yet earned trust. Both are returned; the proven case ranks first at its higher grade weight. score is the rank score in (0, 1] from fusing vector and text search across every searched scope. text is cut to 1,000 characters. Only hits that clear a relevance floor are returned. A native hit needs a similarity of at least 0.2, the same floor as the Knowledge API’s ask; a native hit only text search found has no similarity and is not returned. The floor is applied before the limit cut, so a weak hit never takes a relevant one’s place. 0.2 is an interim value that has not yet been measured against production data. When no hit clears the floor, or the agent has no readable scope, the tool returns { found: false, reason: "no_results", message: "No relevant knowledge found for this query." } and no weak matches. The tool’s description tells the agent to say it doesn’t know, or to ask for what it needs, and never to guess. Nothing is recorded in contextManifests for such a search. When one of the requested scopes is not one the agent may read, the tool searches nothing and returns { found: false, reason: "permission_denied", refusedScope, message }. refusedScope is that scope exactly as the agent sent it. The result is the same whether the scope does not exist or the agent may not read it, so it never shows which. A workflow step records the refusal in contextManifests as permission_denied. When the agent answers a person, it reads only what that person can read. That covers a chat reply, a personal agent, a Factory Manager reply to a person’s message and a Workflow Architect builder turn. A workflow step keeps the agent’s own access, whoever started the run. The knowledge.agentOnBehalfNarrowing platform setting decides how this applies. An operator sets it with platformSettings.set. When the person can’t be identified, or has no access to shared knowledge, an enforced search reads nothing and returns { found: false, reason: "not_readable_for_person", message }, and the agent tells them it can’t look that up. Each such chat search writes one contextManifests row with kind: "retrieval" and a narrowing field: the mode, the shadow count (droppedCount) and, when it read nothing, why (failedClosed). No subject or content is recorded. In the Console, a chat turn’s inspector lists each such search under Knowledge access, by the person’s name: Measuring with the shadow count, or Limited. knowledge_list and knowledge_get read through the same narrowing. A record list also needs the person to hold knowledge:read at the record’s source or collection home, as Knowledge in the Console does. grade says how far to trust a case: A retired case is never returned. An operator who holds knowledge:manage and can read the case’s namespace sets any grade with the knowledge.setCaseGrade mutation, which logs the change on the case and writes a knowledge_entry audit event (knowledge_entry_grade_changed). Hits are ordered by the fused score × the grade’s weight, so a proven case ranks above an equally relevant provisional one. The weights are the knowledge.gradeRankWeights platform setting: proven 1.0, provisional 0.8, ungraded 0.8, contested 0.4 unless an admin changes them with platformSettings.set. A stored value that is missing or breaks the order proven ≥ provisional ≥ contested > 0 falls back to these defaults. score is still the unweighted fused score. Because a weight can lift a hit above ones with a higher fused score, Forge ranks a candidate window of three times limit. It doubles the window until no hit ranked below the window in the same search could outrank the last one returned. The window stops at 256 candidates. If the order is still not settled there, the result also carries truncated: true. The fused score depends on how deep the search reads, so the order is exact for the window the search stopped at. A hit outside that window in both the vector and the text search could rank higher in a deeper search, and this search does not read deeper to check. Each hit writes one contextManifests row with kind: "case", the entryId, the namespace and the score. Historical external references remain access-checked and show No longer available without querying their source. A workflow step’s rows carry its run and node ids, and a chat turn’s rows carry its session and turn ids. These rows record what each step or turn retrieved. They are deleted after 180 days, the same window as stepResults. Each native hit also carries a ref, such as k9jzjrs72: k and eight characters derived from the case’s entryId. A case has the same ref in every search and every turn, so a ref an earlier turn left in the conversation still names the same case. The tool asks the agent to cite a result its answer relies on inline, as [ref:k9jzjrs72]. The chat renders the tag as a citation link. After the turn, Forge reads the refs cited in the agent’s answer. For a node with a structured output, that is the reply before the structured output and the output itself. Each cited hit’s contextManifests row is set to cited: true. Each cited case that is still active also gets one knowledgeUses row: the durable record that the case was used. A case gets one use per workflow run, credited to the first node that cited it, or one per chat turn. A cited ref counts only when it matches a case retrieved in the same workflow run or chat session. The ref may come from an earlier turn of that session. A turn-2 use of a case retrieved in turn 1 is credited to turn 2. A ref that matches no retrieved case is ignored, and so is a ref that two retrieved cases share. A case that is retrieved but not cited gets no use. knowledgeUses rows are not deleted by retention.

knowledge_list and knowledge_get

Every agent that receives knowledge_search also receives knowledge_list and knowledge_get. Both need knowledge:read and are dispatch-injected tools. They read through Forge’s core Knowledge read service as the agent, in the scopes knowledge_search reads without scopes. Inside a workflow step, each read is recorded with the run, and a complete result is replayed to the same request later in the run. A list is never partial. A kind that is incomplete or stale, or that a source has not verified, is refused rather than returned in part. A complete list too large for the agent’s context comes back as too_large with its count and digest.

knowledge_record

Every workflow node agent, chat agent and Factory Manager gets knowledge_record. It stores something the agent learned as a case: a knowledge entry with contentType: "case" that other agents can find later. The target must be a namespace the agent can read, and agents never write to company or global. A scope the agent has nothing for (for example factory outside a workflow run) is refused before anything is written. Every case records the run, node and agent that wrote it, and starts with grade provisional. An agent’s rewrite of a proven case does not replace it (see pending revisions). Any other replacement sets the case back to provisional, with its success and failure counts and its evidence cleared, except a retired case: it stays retired, and only an operator can restore it. Replacing also closes the case’s pending review items (approval, contest, conflict), since they were about the old text. Each create writes a knowledge_entry_created audit event and each replace a knowledge_entry_replaced one (with versionFrom and versionTo), in the same transaction as the case. The tool returns { knowledgeEntryId, caseKey, namespace, replaced }, plus revisionOf when the write was held as a pending revision, and superseded: true when nothing was stored (a newer write of the key landed first, or a person’s edit of the case is waiting for review), or { error } when it refuses. A case keeps its history. Each replacement stores the old version (its text, grade, counts, evidence and the run that wrote it) in knowledgeEntryVersions, and the case keeps its entry id, so earlier uses still point at it. knowledge.caseHistory.listCaseVersions (knowledge:read) returns the 20 newest versions of a case in a namespace the caller can read. Deleting a case also clears the text of every version. Every write is checked against the version of the key it read when it started, and a delete counts as a version. If the case is deleted after that read, the write is dropped and nothing is stored, so a deleted case never comes back from a write that started before the delete. A write that starts after the delete records a new case under the key. The call then fails with the message “the case was deleted while this write was in progress; nothing was stored”. It returns no entry id, and the call’s tool audit row is marked failed (tool_error).

Pending revisions

When an agent rewrites a proven case, or a case that already has a pending revision, the proven text keeps serving. The new text is stored as a pending revision: a second entry with no key of its own, whose revisionOf names the proven case. It starts provisional with its own entry id, so it is searched, cited and graded on its own. knowledge_record returns the revision’s id with revisionOf set and replaced: false. Another agent rewrite replaces the pending revision’s text, and the text it replaced is kept as a version with disposition: "superseded". The same text again changes nothing. A case has at most one pending revision. While that revision is a person’s edit made in the Console, which waits for a person’s approval, an agent’s rewrite stores nothing and returns superseded: true.
  • Promotion. When the revision becomes proven, the proven case takes its text, version, counts and evidence, and the old text is kept as a version. A revision becomes proven through its own successes, or through a person’s approval in a company or global scope. The revision entry is then deleted.
  • Discard. A rewrite of the case by a person or by the system, or a person retiring the revision or the case, discards the revision. So does deleting the case. The revision’s text is kept as a version with disposition: "discarded" until the case itself is deleted.
  • Conflicts. Each revision is checked against the proven case by the judge-knowledge-conflict judge. If following one text would contradict the other, a conflict item names the proven case in the steward queue, and when the judge is confident the revision (never the proven case) also becomes contested. A contested revision stays until a person decides. If the judge is not available, the check is skipped.
knowledge.caseHistory.getCaseRevision (knowledge:read) returns a case’s pending revision, or null, to a caller who can read the case’s namespace. The Console cases list does not show revisions. A version number is never reused: a pending or discarded revision counts toward the key’s version.

knowledge_report_outcome

Every workflow node agent gets knowledge_report_outcome. Chat agents and the Factory Manager do not, because an outcome needs a run. A step uses it to report how a run turned out: a close that tied out is a success, a reopened ticket is a failure. Only a production run reports, and only on a production run: a test (draft) run is refused with { error }, so a draft never grades a case. The report applies to every case the target run has cited so far (its knowledgeUses). It returns { runId, usesUpdated, promoted, contested, queued, continued, memorySignals }; memorySignals counts the long-term memories whose signal for the run was recorded or changed (see How a memory becomes a case).

How outcomes grade a case

Four sources send outcome signals for a run’s cited cases: A fifth source, chat, grades the cases an agent’s chat answer cited. A person’s 👍 on the answer counts +1 and a 👎 −1, in any skin tone. Above zero the answer is a success, below zero a failure, and at zero it gives no signal, which withdraws an earlier one. Other emoji and agents’ reactions are not votes. On an answer that quotes source-restricted knowledge, only people allowed to read it count. The signal applies to the cases that answer’s turn cited, and each case counts it once per answer however many people vote. So one answer weighs at most as much as one run’s outcome. A chat turn has no other source, so chat is not part of knowledge.signalPrecedence. Each case counts at most one signal per run. When sources disagree, the first in the list above wins, so a workflow’s domain outcome outranks an operator’s rating, and the rating outranks the Judge. When a run’s rating and its domain outcome give opposite signals, the case also goes to the steward queue as a contested item that names both, without changing its grade. Sending the same signal again changes nothing. A new signal that reverses an earlier one moves the case’s counters back. A provisional case becomes proven after 3 successes in a row since its last failure, grade change or rewrite. A company or global case is never promoted automatically: it goes to the steward queue for a person to approve. A failure makes a provisional or proven case contested and queues it for a steward, unless it comes from system. A failed run doesn’t show which cited case was wrong, so it counts as a failure and ends the streak but never contests. A failure from another source on the same run, before or after the run failed, contests the case whenever it decides the run’s signal under knowledge.signalPrecedence. A contested or retired case only gains evidence; a person decides its grade with knowledge.setCaseGrade, which also closes its queued items. Rewriting a case restarts its streak and closes a pending approval, because the new text has not earned proven. A test run’s outcome grades nothing. Every automatic grade change writes a knowledge_entry_grade_changed audit event with the actor system:knowledge-outcome. These are platform settings, changed with platformSettings.set: A missing or invalid value falls back to its default.

How a memory becomes a case

An agent’s long-term memory becomes a case only when both of these hold:
  1. It has been retrieved at least knowledge.memoryPromotionRetrievalThreshold times.
  2. A production run that recalled it succeeded. A workflow node’s memory recall is recorded in the run’s context manifest, and each outcome signal for that run is recorded for every memory it recalled, with the same sources and precedence as for cases.
Retrieval count alone never promotes a memory, and neither does a failure. A memory recalled only in chat has no run outcome, so it is not promoted automatically; a person can still promote it from the Console. A daily sweep promotes the memories that qualify. The promoted case starts provisional and earns proven like any other case. It is keyed to its memory (memory:<memoryId>), so a memory becomes at most one case, and its text is redacted before it is stored. It lands in the memory’s originating scope, where the memory was written, never the scope of the run that recalled it: that run only supplies the outcome. A Factory Manager’s memory lands in its factory, and a memory stored in a project stays in that project. A memory a run wrote lands in the agent’s home scope for that run: its project, else its factory, else the agent’s team or the agent itself. Any other memory lands in the agent’s home scope. A personal assistant’s memory is the exception: it is promoted automatically only into its owner’s personal scope, whatever project or run it was written in, and not at all when the owner has no worker. A memory whose agent no longer exists isn’t promoted automatically either. A person can still promote a memory anywhere they’re allowed. When the originating scope can’t be determined, because the run that wrote the memory is gone or was never recorded, the memory is never promoted. Every promotion writes a knowledge_entry_created audit event naming the memory and its tier, never its text. Forgetting the memory deletes a case promoted automatically; a case a person promoted stays.

Case curator

Every Monday at 03:00 UTC, the case curator sweeps the active cases, oldest first.
  • Identical cases are merged. Two active cases in the same namespace with the same title and text are the same case. The curator finds them by the digest a keyed write stores, so it compares cases written by knowledge_record (every such case has a key); a case written before case versioning is compared once it is next rewritten. The curator keeps one: a proven case over a provisional one, then the one with more successes, then the older one. The kept case takes the other’s success and failure counts and its evidence, and gets a knowledge_entry_merged audit event. The other case is deleted for real, like any deleted case: its text and its versions’ text are cleared, and a write to its key that started before the merge is dropped. Its grade is not carried over, and no grade changes.
  • Some duplicates wait for a person. A case a person wrote (an upload, a memory a person promoted, or a case a person recorded) is never deleted by the curator, and neither is a contested case. The curator queues each such copy for a steward as a duplicate review item that names the case it would keep. It withdraws the item once no identical case remains.
  • Unused cases are flagged, never retired. A case is flagged when nobody has used or rewritten it for knowledge.staleAfterDays and no steward has answered a stale flag on it in that time. The curator queues it as a stale review item. The flag changes nothing on the case; only a steward retires one, with knowledge.setCaseGrade. The curator withdraws the flag once the case is used or rewritten again. Retiring a case closes its pending stale and duplicate items.
Uses and citations of a merged-away case keep pointing at its deleted entry, so a late outcome for a run that cited it grades nothing. Running the curator again changes nothing until the cases do.

Durable blackboard notes

A blackboard is scratch state for one workflow run or chat session. It is archived when the run ends or the session closes, and the next run starts with an empty board. To keep a note past that point, the agent marks it durable: A board keeps at most 25 durable notes. A write or patch that would leave more is refused, and the board is unchanged. A durable note becomes a case in its agent’s home scope, so the board’s scope must include the agent. A write or patch with durable: true is refused, and the board is unchanged, when the scope has no agentId (for example, when a scope override sets agentId to null). blackboard_read returns the board as before. When any key is durable, the result also has a $durableKeys field that lists those keys. $durableKeys is read-only: a write or patch that includes it ignores it. When the run ends (on any terminal path, including cancel) or the session closes, each durable note still on the board is recorded as a case, the same way knowledge_record records one:
  • The note’s key is the title (up to 200 characters). Its value is the content: a string is used as-is, and any other value is stored as JSON with sorted keys.
  • The case goes in the agent’s home scope, with grade provisional and source agent_record. It records the run that wrote it, if there was a run. Its knowledge_entry audit event has origin: "blackboard" in its detail.
  • The key is sha256: plus a hash of the full note key and the content, taken before the title is cut to 200 characters. The same note from later runs stays one case, and two notes whose keys differ only after 200 characters are two cases. If a live case already has that key, it is left as it is, grade included.
  • The title and content are redacted before the limits below are checked and before the key is hashed.
A note whose content is over 20,000 characters, or empty, is skipped. A note that fails to record is logged, and the board’s other notes are still recorded. Recording is retried until each note is recorded, up to 5 attempts 15 minutes apart: a retry records only the notes that failed, and an attempt that stopped partway is run again. Each recorded note is marked on the board in the same write as its case, and a retry skips marked notes. A retry never creates a case twice, and never re-creates a case that was deleted after it was recorded. A note whose case was deleted while it was being recorded is not retried. If notes still fail after the last attempt, or the last attempt stops partway, their case keys are kept on the archived board as promotionAbandoned, and the failure is logged as blackboard.durable_notes_abandoned. Notes that are not durable are never recorded: they stay only on the archived board.

Color legend