> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> Forge MCP tool discovery, inputs, outputs, toolsets, scopes, permissions, and risk metadata.

`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:

```json theme={"system"}
{
  "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.

## 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 fleet 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`:

```json theme={"system"}
{
  "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.