Tool Reference

tools/list is the authoritative tool reference for the current actor. Forge builds each definition from the same capability registry used by the REST API and CLI. Each advertised tool contains:

{
  "name": "forge_inventory_search",
  "title": "Search Forge inventory",
  "description": "Search AI products, agents, identities, MCP servers, skills, capabilities, tools, models, policies, and inventory evidence.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "annotations": {
    "readOnlyHint": true
  },
  "_meta": {
    "forge/capabilityId": "inventory.read",
    "forge/domain": "inventory",
    "forge/riskTier": "sensitive_read",
    "forge/requiredScopes": ["inventory:read"],
    "forge/requiredPermission": "telemetry.read",
    "forge/toolset": "default-read",
    "forge/stability": "beta"
  }
}

Clients should render and validate the returned inputSchema; do not maintain a separate permissive schema. Tool schemas reject unknown properties.

Search a large tool catalog

If your MCP client supports a search-first tool flow, send X-Forge-Tool-Search: 1 with tools/list. Forge then advertises forge_search_tools instead of loading every tool schema into the client. Call it with a query to find tools available to the current actor, then use the returned tool definitions for subsequent calls. Forge checks access again when each tool is called, so a search result does not grant access by itself. Install an API-backed integration in Registry → From API and configure its client access before searching its tools. The search only includes tools the actor can use. Clients that do not send the header continue to receive the normal tools/list response.

Discovery tools

Tool	Purpose
`forge_capabilities_list`	Return Forge capabilities and authorization results for the actor.
`forge_inventory_search`	Search the organization inventory across products, agents, identities, MCP servers, skills, tools, models, policies, and evidence.
`forge_inventory_item_get`	Read one bounded inventory dossier by item identifier and requested view.
`forge_inventory_related_list`	Traverse one bounded relationship from an inventory item.

Investigation tools

Tool	Purpose
`forge_activity_search`	Search bounded session and traffic activity by product, user, device, integration, risk, and time.
`forge_activity_aggregates_get`	Read exact activity totals and bounded breakdowns using canonical filters.
`forge_llm_gateway_usage_get`	Read usage, token, cost, and policy-outcome aggregates observed by Forge LLM Gateway.
`forge_session_get`	Read one exact compact, redacted session and continue with its opaque cursor when necessary.
`forge_findings_search`	Search findings by severity, state, related resources, basis, time, or text.
`forge_finding_get`	Read one finding with bounded evidence and related pivots.

Policy tools

Tool	Purpose
`forge_policies_search`	Search Content, Access, and skill ACL policies.
`forge_policy_get`	Read one policy; definition JSON is opt-in and bounded.
`forge_policy_impact_get`	Read violation occurrences and impact metrics for one policy.
`forge_policy_violations_search`	Search cross-policy violation occurrences and optional evidence.

Governance tools

Tool	Purpose
`forge_governance_search`	Search requests, grants, and interventions.
`forge_governance_get`	Read one governance item.
`forge_governance_request_resolve`	Approve or deny a request with reason, idempotency, and confirmation.
`forge_governance_grant_revoke`	Preview or revoke an active grant.
`forge_governance_intervention_create`	Create a session intervention.
`forge_governance_intervention_clear`	Clear an intervention.

MCP approval tools

Tool	Purpose
`forge_mcp_approvals_search`	Search approval requests visible to reviewers.
`forge_my_mcp_approvals_search`	Search requests created by the current actor.
`forge_mcp_approval_get`	Read one request when the actor owns it or has reviewer access.
`forge_mcp_approval_create`	Create an MCP approval request and optionally start scanning.
`forge_mcp_approval_approve`	Approve a request.
`forge_mcp_approval_deny`	Deny a request with justification.
`forge_mcp_approval_scanner_run`	Start an approval scanner run.
`forge_mcp_approval_policy_suggestion_update`	Update a scanner-generated policy suggestion.

Assurance tools

Tool	Purpose
`forge_compliance_posture_get`	Read framework-level compliance posture.
`forge_compliance_controls_search`	Search item-level controls and evidence gaps.
`forge_audit_search`	Search organization audit events by actor, target, action, and time.
`forge_audit_anomalies`	List bounded headless-access anomaly indicators.

Administration tools

Tool	Purpose
`forge_service_accounts_search`	Search non-secret service-account posture.
`forge_mcp_sessions_search`	Search remote MCP sessions by actor, account, client, scope, toolset, and status.
`forge_mcp_session_revoke`	Revoke a remote MCP session.
`forge_fleet_devices_search`	Search canonical and provider-owned device posture.
`forge_fleet_posture_get`	Read device deployment posture grouped by source and runtime state.
`forge_fleet_action_create`	Preview or create a device action.
`forge_managed_config_search`	Search managed-configuration profiles.
`forge_managed_config_get`	Read one profile with redacted controls and release references.
`forge_managed_config_profile_preview`	Compile and preview a profile.
`forge_managed_config_profile_publish`	Preview or publish a profile release.
`forge_managed_config_profile_rollback`	Preview or roll back to a prior release.
`forge_headless_settings_get`	Read service-account, MCP, and built-in-agent security settings.
`forge_headless_settings_update`	Update those organization settings as a guarded mutation.

Calling a tool

Use the exact schema returned by tools/list:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "forge_inventory_search",
    "arguments": {
      "query": "Claude",
      "kinds": ["agent", "mcp_server"],
      "limit": 25
    }
  }
}

Forge validates the call again at execution time. A tool that appeared earlier can still be denied if the session was revoked, organization settings changed, the actor lost access, or required mutation safeguards are absent.

Mutation inputs

Guarded mutation tools expose applicable fields directly in their inputSchema:

Input	Contract
`reason`	Required human-readable justification where declared.
`idempotencyKey`	Required stable identity for one logical mutation where declared.
`dryRun`	Requests validation and impact without final execution where supported.
`confirm`	Must be `true` for capabilities requiring explicit final confirmation.

The fields are forwarded to the underlying Forge capability as safety headers and request-body values. They are not generic prompt instructions.

Output limits

Tool text content is bounded to protect the MCP session. Successful results also include the underlying object in structuredContent.result. Search tools expose their own cursor or offset semantics. forge_inventory_search additionally returns resultCount, totalMatching, hasMore, nextOffset, and a pagination object. Do not treat a bounded search page as an organization-wide total. forge_activity_aggregates_get computes exact totals across all activity that matches its canonical filters, while returning bounded dimension breakdowns. forge_llm_gateway_usage_get does the same for usage observed through Forge LLM Gateway. Search tools should be continued using the pagination fields returned by that specific tool. MCP call audit records store the tool, capability, decision, reason, request ID, and redacted bounded input/output summaries. Inputs containing credential-shaped fields are redacted from the summary.

​Search a large tool catalog

​Discovery tools

​Investigation tools

​Policy tools

​Governance tools

​MCP approval tools

​Assurance tools

​Administration tools

​Calling a tool

​Mutation inputs

​Output limits