The MCP tool catalog

The canonical MCP tool catalog is apps/ai-coo-cf/src/tools/catalog.ts. It defines the tools exposed by the Cloudflare Worker runtime. Files under apps/ai-coo/ are compatibility and local-development code, not the source for production discovery.

Catalog shape

Each normalized ToolDefinition contains:

Field	Meaning
`name`	Canonical `inblack_*` tool name
`description`	Agent-facing capability description
`tier`	Risk tier: `T1`, `T2`, `T3`, or `T4`
`pillar`	`accounting`, `commerce`, `cx`, `portal`, `reporting`, or `studio`
`kind`	`read`, `write`, or `simulate`
`schema`	Zod input shape used for validation and MCP input-schema generation
`outputSchema`	Structured output contract
`errorCodes`	Declared `INBLACK_*` errors for the tool
`pagination`	`cursor` or `none`
`provenance`	`required` for writes; `not_applicable` otherwise
`surfaces`	Public/internal exposure
`visibility`	Feature, entitlement, GL-layer, role, permission, and persona requirements
`simulatedBy` / `simulates`	Links a write to its generated preview tool
`deterministic`	Replay and canonicalization metadata

The catalog contains metadata and schemas. Execution is handled by the MCP router and its delegates; a handler is not embedded in each catalog entry.

Risk tiers

Tier	Catalog meaning	Runtime behavior
`T1`	Read-only, report, search, or simulation	Executes without a pending action
`T2`	Low-risk write	Usually executes immediately; guardrail scoring can escalate it to review
`T3`	Mutating write	Creates a pending action before execution
`T4`	Destructive action	Internal-only in discovery; curated tools are hard-blocked and other allowed tools require destructive approval

Studio API-key rotation and revocation are also approval-required even though their catalog tier is T2.

Generated simulate tools

Every normalized write has a generated inblack_simulate_* twin. The simulate tool is kind: "simulate", tier: "T1", and links back through simulates; the write links forward through simulatedBy.

The complete unfiltered catalog currently contains 440 tools: 128 reads, 155 writes, and 157 simulations. Runtime results can be smaller because manifests and tools/list are filtered for the surface, tenant policy, and principal.

Visibility

Visibility is not encoded as fictional tier-name arrays on each tool. The Worker combines catalog metadata with the tenant’s current agent policy and principal:

Surface exposure
AI assistant enabled state
Effective risk tier and destructive-action policy
AI COO scope
Enabled pillar
Required features
Minimum GL layer
Required entitlements
Allowed roles
Required permissions
Allowed personas

A tool that fails a gate is omitted from discovery. Tenant-scoped policy resolution fails closed when the Worker cannot verify the tenant’s AI policy.

See Pillars, tiers, and tool visibility for the full model.

Manifest contract

The public machine-readable catalog is:

GET https://ai-coo.inblack.app/mcp/manifest
Authorization: Bearer <zitadel-access-token>
X-Tenant-ID: <tenant-id>

The response identifies the canonical catalog and runtime contract:

{
  "schema_version": "2026-05-01",
  "canonical_catalog": "apps/ai-coo-cf/src/tools/catalog.ts",
  "surface": "public",
  "endpoint_path": "/mcp",
  "transport": "mcp_streamable_http",
  "auth": "zitadel_bearer",
  "visibility_schema_version": "2026-05-01",
  "tool_count": 0,
  "counts_by_kind": { "read": 0, "write": 0, "simulate": 0 },
  "counts_by_pillar": {
    "accounting": 0,
    "commerce": 0,
    "cx": 0,
    "portal": 0,
    "reporting": 0,
    "studio": 0
  },
  "tools": []
}

Each manifest tool entry exposes metadata and sorted input_schema_keys, not the full Zod or output schema. Use MCP tools/list for the protocol-level tool definitions.

The internal manifest is at /internal/mcp/manifest. It uses service_token_or_internal_scope auth and includes internal-surface definitions, including T4 entries, subject to policy filtering.

Catalog checks

From inblack-userguide/docs, run:

pnpm check:mcp

This checks the generated catalog and all generated pillar reference pages against the current platform source.