:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import z from 'zod'
import { hasScope, hasScopes } from '@/lib/api'
import { OAUTH_SCOPES_SUPPORTED } from '@/lib/oauth-scopes.generated'
import type { EvaluatedFlags } from '@/lib/posthog/flags'
import { isStaffOnlyTool } from '@/lib/staff-only-tools'
import { formatNotebookWidgetCatalogForAgents } from '@/tools/notebooks/widgetCatalog'
import generatedToolDefinitionsJson from '../../schema/generated-tool-definitions.json'
import toolDefinitionsJson from '../../schema/tool-definitions.json'
export const ToolDefinitionSchema = z
.object({
description: z.string(),
category: z.string(),
feature: z.string(),
summary: z.string(),
title: z.string(),
required_scopes: z.array(z.string()),
requires_ai_consent: z.boolean().optional(),
/** PostHog feature flag key that gates this tool. */
feature_flag: z.string().optional(),
/** How the flag gates the tool: 'enable' (default) or 'disable'. */
feature_flag_behavior: z.enum(['enable', 'disable']).optional(),
/** Variant of `feature_flag` to match exactly. Requires `feature_flag` to be set. */
feature_flag_variant: z.string().optional(),
/**
* Additional gate: hide the tool whenever this flag is on, independent of
* `feature_flag`. For retiring a tool under a successor surface's rollout
* flag while the tool keeps its own gating flag.
*/
hidden_when_flag_on: z.string().optional(),
/**
* Tool names that took over this tool's job. Declared next to the gate
* that retires the tool, so a call to the retired name can name its
* successor instead of reporting the name as unknown.
*/
superseded_by: z.array(z.string()).optional(),
/** Extra guidance appended to the successor message, for a redirect a bare tool name cannot carry. */
redirect_hint: z.string().optional(),
/**
* The Django endpoints the handler calls, as `METHOD /path` with OpenAPI path templates.
* A narrowed scout run is refused a non-GET call when no tool it holds lists the endpoint.
*/
api_operations: z.array(z.string()).optional(),
/**
* AvailableFeature the org's plan must include for this tool to be
* advertised (e.g. `'audit_logs'`), matching the backend's
* `premium_feature_on_cloud`. Best-effort — the backend
* `PremiumFeaturePermission` stays authoritative; the gate is fail-open.
*/
feature_entitlement: z.string().optional(),
/** One-line selection hint surfaced in the system prompt's query tool catalog. */
system_prompt_hint: z.string().optional(),
search_keywords: z.array(z.string()).optional(),
/**
* When true, the tool is exposed even when the client passes a `features`
* or `tools` allowlist that wouldn't otherwise match. Reserved for
* cross-cutting utility tools (e.g. feedback) that should remain
* discoverable to every client without forcing them to opt in.
* Other filters (readOnly, AI consent, feature flags, scopes) still apply.
*/
always_available: z.boolean().optional(),
annotations: z.object({
destructiveHint: z.boolean(),
idempotentHint: z.boolean(),
openWorldHint: z.boolean(),
readOnlyHint: z.boolean(),
}),
})
.refine((data) => !(data.feature_flag_variant && !data.feature_flag), {
message: '`feature_flag_variant` requires `feature_flag` to be set',
path: ['feature_flag_variant'],
})
export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>
export type ToolDefinitions = Record<string, ToolDefinition>
const toolDefinitionsSchema = z.record(z.string(), ToolDefinitionSchema)
let _toolDefinitions: ToolDefinitions | undefined = undefined
let _generatedToolDefinitions: ToolDefinitions | undefined = undefined
let _mergedToolDefinitions: ToolDefinitions | undefined = undefined
const NOTEBOOK_BUILDER_TOOL_NAMES = ['notebooks-create', 'notebooks-create-markdown', 'notebooks-add-cell'] as const
function addNotebookWidgetCatalog(definitions: ToolDefinitions): ToolDefinitions {
const widgetCatalog = formatNotebookWidgetCatalogForAgents()
const enrichedDefinitions = { ...definitions }
for (const toolName of NOTEBOOK_BUILDER_TOOL_NAMES) {
const definition = enrichedDefinitions[toolName]
if (definition) {
enrichedDefinitions[toolName] = {
...definition,
description: `${definition.description}\n\n${widgetCatalog}`,
}
}
}
return enrichedDefinitions
}
function getGeneratedToolDefinitions(): ToolDefinitions {
if (!_generatedToolDefinitions) {
_generatedToolDefinitions = toolDefinitionsSchema.parse(generatedToolDefinitionsJson)
}
return _generatedToolDefinitions
}
// Both sources are immutable module JSON, so the merge is memoised alongside them:
// the analytics hot path calls this twice per tool call (category + description),
// and rebuilding the whole record each time is pure waste.
export function getToolDefinitions(): ToolDefinitions {
if (!_mergedToolDefinitions) {
if (!_toolDefinitions) {
_toolDefinitions = toolDefinitionsSchema.parse(toolDefinitionsJson)
}
_mergedToolDefinitions = addNotebookWidgetCatalog({ ..._toolDefinitions, ...getGeneratedToolDefinitions() })
}
return _mergedToolDefinitions
}
let _advertisedOAuthScopes: readonly string[] | undefined = undefined
/**
* Scopes published as `scopes_supported` in the MCP protected-resource
* metadata: every grantable scope the tool catalog requires, plus identity
* scopes (no `:`) that ride every authorize. Narrower than
* `OAUTH_SCOPES_SUPPORTED` (the authorization server's full grantable set) so
* clients are not asked to consent to write access no tool exercises. Filtering
* `OAUTH_SCOPES_SUPPORTED` keeps the result a subset of the AS, so no advertised
* scope is rejected at `/authorize`.
*/
export function getAdvertisedOAuthScopes(): readonly string[] {
if (!_advertisedOAuthScopes) {
const required = new Set<string>()
for (const definition of Object.values(getToolDefinitions())) {
for (const scope of definition.required_scopes ?? []) {
required.add(scope)
}
}
_advertisedOAuthScopes = OAUTH_SCOPES_SUPPORTED.filter((scope) => !scope.includes(':') || required.has(scope))
}
return _advertisedOAuthScopes
}
export function getToolDefinition(toolName: string): ToolDefinition {
const toolDefinitions = getToolDefinitions()
const definition = toolDefinitions[toolName]
if (!definition) {
throw new Error(`Tool definition not found for: ${toolName}`)
}
return definition
}
/**
* The product category a tool belongs to (e.g. "Logs", "Tracing"), or undefined
* for tools without a catalogued definition (e.g. the `exec` wrapper). Unlike
* {@link getToolDefinition} this never throws, so it is safe to call from the
* analytics hot path where a missing definition must not break the request.
*/
export function getToolCategory(toolName: string): string | undefined {
return getToolDefinitions()[toolName]?.category
}
/**
* Catalogued descriptions run to ~13 KB (the query tools embed full usage guides), which
* is too heavy to stamp on every analytics event. The first 512 characters carry the
* lead paragraph, which is the part that describes what the tool is for.
*/
export const MAX_CAPTURED_DESCRIPTION_LENGTH = 512
/**
* The description a tool advertises to agents, clipped for analytics capture, or
* undefined for tools without a catalogued definition (e.g. the `exec` wrapper).
* Like {@link getToolCategory} this never throws, so it is safe to call from the
* analytics hot path where a missing definition must not break the request.
*/
export function getToolDescription(toolName: string): string | undefined {
return getToolDefinitions()[toolName]?.description?.slice(0, MAX_CAPTURED_DESCRIPTION_LENGTH)
}
export interface ToolFilterOptions {
features?: string[] | undefined
tools?: string[] | undefined
excludeTools?: string[] | undefined
readOnly?: boolean | undefined
aiConsentGiven?: boolean | undefined
/** Used to gate tools that declare `feature_flag` in their YAML config. */
featureFlags?: EvaluatedFlags | undefined
/**
* Project IDs the token is restricted to (`scoped_teams` on the API key).
* When set, the backend 403s any org-level endpoint, so we drop tools that
* need `organization:*` scopes — they'd fail anyway.
*/
scopedTeams?: number[] | undefined
/** Org's plan entitlements (`available_product_features` keys). Undefined when unresolved. */
availableFeatures?: string[] | undefined
/** Whether the API this MCP talks to is PostHog Cloud. Off-cloud is never entitlement-gated. */
isCloud?: boolean | undefined
}
/**
* Collect all distinct feature flag keys referenced by tool definitions.
* Used at init time to batch-evaluate flags before filtering tools.
*/
export function getRequiredFeatureFlags(): string[] {
const toolDefinitions = getToolDefinitions()
const flags = new Set<string>()
for (const definition of Object.values(toolDefinitions)) {
if (definition.feature_flag) {
flags.add(definition.feature_flag)
}
if (definition.hidden_when_flag_on) {
flags.add(definition.hidden_when_flag_on)
}
}
return [...flags]
}
function normalizeFeatureName(name: string): string {
return name.replace(/-/g, '_')
}
/**
* Predicate: does a tool's `feature_flag` configuration permit it under the
* given evaluation map? An undefined map is treated as "no flags evaluated".
*
* `hidden_when_flag_on` set and that flag is on → always hidden
* no `feature_flag` → always passes
* `feature_flag_variant` set → flag value must equal the variant string
* `feature_flag_behavior: 'enable'` (default) → flag must be `=== true`
* `feature_flag_behavior: 'disable'` → flag must NOT be `=== true`
*/
export function toolPassesFlagGate(definition: ToolDefinition, featureFlags: EvaluatedFlags = {}): boolean {
if (definition.hidden_when_flag_on && featureFlags[definition.hidden_when_flag_on] === true) {
return false
}
if (!definition.feature_flag) {
// Belt-and-braces: the schema `.refine` rejects this at parse time, but
// `z.infer` strips refinements so TS lets callers hand-roll a bad
// ToolDefinition. Treat the misconfig as "always hidden" rather than
// silently ungated.
return definition.feature_flag_variant === undefined
}
const flagValue = featureFlags[definition.feature_flag]
if (definition.feature_flag_variant !== undefined) {
return flagValue === definition.feature_flag_variant
}
const isOn = flagValue === true
return (definition.feature_flag_behavior ?? 'enable') === 'enable' ? isOn : !isOn
}
/**
* Predicate: is a tool's `feature_entitlement` satisfied for this org? Fail-open,
* mirroring the backend `premium_feature_on_cloud` semantics:
*
* no feature_entitlement → pass (ungated)
* isCloud === false (self-hosted) → pass (backend never gates off-cloud)
* availableFeatures unknown → pass (couldn't resolve; backend authoritative)
* feature ∈ availableFeatures → pass
* otherwise (cloud + absent) → hide
*/
export function toolPassesEntitlementGate(
definition: ToolDefinition,
availableFeatures?: string[],
isCloud?: boolean
): boolean {
if (!definition.feature_entitlement) {
return true
}
if (isCloud === false) {
return true
}
if (availableFeatures === undefined) {
return true
}
return availableFeatures.includes(definition.feature_entitlement)
}
/**
* Every catalog filter, with the flag gate optional: {@link getToolsForFeatures}
* drops what the flags hide, {@link getFlagGatedTools} keeps exactly that set.
*/
function filterToolEntries(options: ToolFilterOptions | undefined, applyFlagGate: boolean): [string, ToolDefinition][] {
const { features, tools, readOnly, aiConsentGiven, featureFlags, scopedTeams, availableFeatures, isCloud } =
options || {}
const toolDefinitions = getToolDefinitions()
let entries = Object.entries(toolDefinitions)
// Filter by features and/or tools allowlist (OR union).
// When both are provided, a tool is included if it matches a feature category OR is in the tools list.
// Normalize hyphens to underscores so that both "error-tracking" and "error_tracking" match.
// Tools marked `always_available` bypass this allowlist so utility tools
// (e.g. feedback) stay discoverable for every client.
const hasFeatures = features && features.length > 0
const hasTools = tools && tools.length > 0
if (hasFeatures || hasTools) {
const normalizedFeatures = hasFeatures ? new Set(features.map(normalizeFeatureName)) : null
const allowedTools = hasTools ? new Set(tools) : null
entries = entries.filter(([toolName, definition]) => {
if (definition.always_available) {
return true
}
const matchesFeature = normalizedFeatures
? definition.feature && normalizedFeatures.has(normalizeFeatureName(definition.feature))
: false
const matchesTool = allowedTools ? allowedTools.has(toolName) : false
return matchesFeature || matchesTool
})
}
// In read-only mode, only expose tools annotated as read-only
if (readOnly) {
entries = entries.filter(([_, definition]) => definition.annotations.readOnlyHint === true)
}
// When AI consent is not given or not yet fetched, exclude tools that require it
if (!aiConsentGiven) {
entries = entries.filter(([_, definition]) => !definition.requires_ai_consent)
}
// Filter by feature flags — see {@link toolPassesFlagGate} for the predicate.
if (applyFlagGate) {
entries = entries.filter(([_, definition]) => toolPassesFlagGate(definition, featureFlags))
}
// Filter by billing entitlement — see {@link toolPassesEntitlementGate}.
entries = entries.filter(([_, definition]) => toolPassesEntitlementGate(definition, availableFeatures, isCloud))
// Hide tools that need org-level access when the session's token is
// project-scoped - the backend would 403 them
if (scopedTeams && scopedTeams.length > 0) {
entries = entries.filter(
([_, definition]) => !(definition.required_scopes ?? []).some((scope) => scope.startsWith('organization'))
)
}
return entries
}
export function getToolsForFeatures(options?: ToolFilterOptions): string[] {
return filterToolEntries(options, true).map(([toolName, _]) => toolName)
}
export interface FlagGatedTool {
name: string
/** Tool names the definition declares as this tool's successors, in the order it lists them. */
supersededBy: string[]
/** Free-text guidance the definition adds to the redirect. */
redirectHint?: string
}
/**
* Tools a feature flag removed from the active catalog, while every other filter
* kept them. The exec dispatcher reads this so a call to a retired name reports
* the successor, or reports that the tool is not enabled — never that the name
* is unknown, which reads to an agent as a removed capability.
*
* Staff-only tools are left out for the same reason {@link getScopeGatedTools}
* leaves them out: the hint would advertise a staff surface to a customer.
*/
export function getFlagGatedTools(options?: ToolFilterOptions): FlagGatedTool[] {
const excluded = new Set(options?.excludeTools ?? [])
const gated: FlagGatedTool[] = []
for (const [name, definition] of filterToolEntries(options, false)) {
if (excluded.has(name) || toolPassesFlagGate(definition, options?.featureFlags)) {
continue
}
if (isStaffOnlyTool(definition.required_scopes ?? [])) {
continue
}
gated.push({
name,
supersededBy: definition.superseded_by ?? [],
...(definition.redirect_hint ? { redirectHint: definition.redirect_hint } : {}),
})
}
return gated
}
export interface ScopeGatedTool {
name: string
title: string
description: string
searchKeywords?: string[]
/** Scopes the tool requires that the current API key is missing. */
missingScopes: string[]
requiredScopes: readonly string[]
}
/**
* Tools that pass every filter except the API key's scopes — i.e. they exist
* and are enabled for this session's features, but the token lacks the scopes
* to call them. Surfaced by the exec `search` command so an agent gets an
* actionable "add this scope" hint instead of silently concluding the tool is
* missing.
*/
export function getScopeGatedTools(scopes: string[], options?: ToolFilterOptions): ScopeGatedTool[] {
const toolDefinitions = getToolDefinitions()
const excluded = new Set(options?.excludeTools ?? [])
const gated: ScopeGatedTool[] = []
for (const name of getToolsForFeatures(options)) {
if (excluded.has(name)) {
continue
}
const definition = toolDefinitions[name]
const required = definition?.required_scopes ?? []
if (!definition || required.length === 0 || hasScopes(scopes, required)) {
continue
}
// Never hint at staff-only tools — an "add this scope" nudge would
// advertise a staff surface to customers who can never call it.
if (isStaffOnlyTool(required)) {
continue
}
gated.push({
name,
title: definition.title,
description: definition.description,
searchKeywords: definition.search_keywords,
missingScopes: required.filter((scope) => !hasScope(scopes, scope)),
requiredScopes: required,
})
}
return gated
}