MCP tool reference

Radiant’s MCP tools let an external assistant discover activity, inspect evidence and work with Meta Agent investigations. Every call is scoped to the connecting credential’s project. Follow External assistants through MCP for connection and credential setup.

Your client’s tools/list response provides the input schemas for its available tools. Unknown fields are rejected. Additional capabilities expose Signal management, shared conversation history and coding handoffs.

Project context

get_project_context

Takes no arguments. Returns project_id, can_manage_signals, can_read_history and can_coding_handoffs. Use it to confirm the project and available capabilities before changing project state.

Trace discovery and inspection

find_traces

Finds retained traces containing matching operations, including non-agent activity. Optional arguments are attribute: { key, value }, exact span_name, RFC 3339 from/to, paired receive-time bounds, limit and cursor. Attribute values must be strings, numbers or booleans. Resource attribute values are strings.

The start-time window is at most 30 days and defaults to the last 30 days unless paired receive-time bounds are supplied. limit accepts 1–100 and defaults to 20.

Returns result.traces, result.has_more and result.next_cursor. Each trace includes matching-operation counts and timestamps alongside totals for the complete retained trace. The complete trace can contain operations outside the discovery filters or time window.

Find traces with an exact application attribute:

{
  "name": "find_traces",
  "arguments": {
    "attribute": { "key": "gen_ai.conversation.id", "value": "conversation-104" },
    "limit": 20
  }
}

Pass the returned result.next_cursor as cursor with the same filters for another page.

inspect_trace

Requires trace_id. Optional span_id restricts inspection to that operation and its descendants. limit accepts 1–200 and defaults to 50; cursor continues the same trace or subtree.

Returns span summaries under result.spans, including parent relationships, timing and available evidence keys, with result.has_more and result.next_cursor. Payloads are read separately with get_span_evidence.

Inspect one trace, optionally restricted to an agent span and its descendants:

{
  "name": "inspect_trace",
  "arguments": {
    "trace_id": "YOUR_TRACE_ID",
    "span_id": "YOUR_ROOT_SPAN_ID",
    "limit": 50
  }
}

Omit span_id for the complete trace.

Agent runs and groups

find_agent_runs

Requires a structured query with source: "agent_runs". Supply query.time_range unless both top-level receive-time bounds are present. Optional limit accepts 1–100 and defaults to 20; cursor continues the same query.

Returns identified top-level invocations in result.agent_runs, with result.has_more and result.next_cursor. Use each run’s trace ID and root span ID with inspect_trace.

This query finds runs from the support-agent service:

{
  "name": "find_agent_runs",
  "arguments": {
    "query": {
      "source": "agent_runs",
      "time_range": {
        "from": "2026-10-28T09:00:00Z",
        "to": "2026-10-28T10:00:00Z"
      },
      "conditions": [
        {
          "operator": "is",
          "field": { "kind": "intrinsic", "field": "service" },
          "value": "support-agent"
        }
      ]
    },
    "limit": 20
  }
}

Open a discovered run with inspect_trace, using its trace ID and root span ID. Pass next_cursor back as cursor with the same query to read another page.

find_groups

Requires a structured query with group_by and start-time bounds, unless paired receive-time bounds are supplied. Sources are agent_runs or spans. Optional limit accepts 1–100 and defaults to 20; cursor continues the same query.

Returns result.groups, result.has_more and result.next_cursor. Discovery conditions select groups through their members; summaries cover each complete bounded group. Groups can overlap, so their totals are not necessarily additive.

inspect_group

Requires selection, started_after and started_before. The selection identifies the source, grouping and exact returned JSON value. Optional limit accepts 1–200 and defaults to 50; cursor continues the same selection and time window.

Returns the selection and paged span summaries in result, using the same membership as the Logs execution view. Read payloads with get_span_evidence. Follow returned next_cursor values to inspect the complete group.

Group discovery and inspection example

Group agent activity by a string gen_ai.conversation.id recorded by your application:

{
  "name": "find_groups",
  "arguments": {
    "query": {
      "source": "agent_runs",
      "time_range": {
        "from": "2026-10-28T09:00:00Z",
        "to": "2026-10-28T10:00:00Z"
      },
      "group_by": { "kind": "attribute", "field": "gen_ai.conversation.id" },
      "conditions": [
        {
          "operator": "is",
          "field": { "kind": "attribute", "key": "gen_ai.conversation.id" },
          "value": "conversation-104"
        }
      ]
    },
    "limit": 20
  }
}

The response’s result.groups array contains group values and summary columns. For this example, the relevant value fragment is:

{ "value": "conversation-104" }

selection accepts source (agent_runs, the default, or spans), group_by ({ "kind": "trace" } or { "kind": "attribute", "field": "KEY" }), and the exact returned value. value_match is typed by default; scalar_text preserves text comparison for historical selections. Optional restrictions are agent_id (agent-run source only), trace_id, and filters, an array of { "field": "KEY", "value": "TEXT" } attribute restrictions.

Construct the inspection selection using the query’s source and grouping, plus that exact returned JSON value:

{
  "name": "inspect_group",
  "arguments": {
    "selection": {
      "source": "agent_runs",
      "group_by": { "kind": "attribute", "field": "gen_ai.conversation.id" },
      "value": "conversation-104",
      "value_match": "typed"
    },
    "started_after": "2026-10-28T09:00:00Z",
    "started_before": "2026-10-28T10:00:00Z",
    "limit": 50
  }
}

Inspection reads the complete group membership in the supplied window, including child spans. Discovery conditions choose which groups to return; they are not filters to remove members from the inspected group. Preserve any restrictions in an existing selection, including its source, grouping, typed value and optional agent or trace identity.

For a numeric group value, retain the number: "value": 104 selects a different typed group from "value": "104". Use { "kind": "trace" } to group by trace identity instead of an attribute.

Trajectories and evidence

get_trajectory

Supply exactly one of trace_id or a group selection. A group also requires started_after and started_before; these bounds are not accepted with a trace ID. Optional max_steps accepts 1–1000 and defaults to 400.

Returns the trajectory graph under result, including steps and observed or inferred connections. Later steps are omitted first when the step limit is reached. Inferred connections are hypotheses, rather than recorded causal relationships.

Tool arguments, results and result-derived error text are omitted from the graph. Retrieve them with get_span_evidence, using the step’s trace and span IDs.

get_span_evidence

Requires trace_id, span_id and 1–4 sections. Each selection names attributes, events, resource_attributes or metadata. Optional pointer uses JSON Pointer syntax; offset defaults to 0 and limit accepts 1–24000 Unicode characters, defaulting to 12000.

Returns independently chunked JSON text for each section, with its pointer, offsets and next_offset. Concatenate all chunks before parsing the selected value. A pointer selects within the recorded section; it does not parse JSON stored inside a string.

Retrieve specific recorded evidence:

{
  "name": "get_span_evidence",
  "arguments": {
    "trace_id": "YOUR_TRACE_ID",
    "span_id": "YOUR_SPAN_ID",
    "sections": [
      { "section": "attributes", "pointer": "/gen_ai.tool.call.result" },
      { "section": "events" }
    ]
  }
}

A pointer selects a value using JSON Pointer syntax. Follow each returned next_offset to retrieve long values before parsing or judging their completeness.

Observations and Signals

list_observations

Optional limit accepts 1–50 and defaults to 20. Optional workflow_id restricts results to attribute-group evidence with key exactly workflow.id and a matching string value; it does not match other grouping fields or trace evidence.

Returns observations with evidence, review windows and Signal verdicts. Only the provider’s recent findings are searched; this tool has no continuation cursor for older history.

list_signals

Optional include_inactive defaults to false. Returns signals, including active criteria and drafts; set the option to include retired definitions.

create_signal

Requires can_manage_signals, title (1–200 characters) and content (1–5000 characters). Optional draft saves a draft when true; creation otherwise activates the Signal. Optional client_request_id accepts 1–200 characters. Reuse it when retrying the same creation to avoid duplicates.

Returns the created definition under signal, including its stable memory_id. If creation succeeds but its state cannot be confirmed, inspect it with list_signals before trying another creation.

promote_signal and deactivate_signal

Require can_manage_signals and memory_id. Promotion activates a draft or reactivates an inactive Signal. Deactivation stops future checks while preserving the definition and past verdicts. Responses return the resulting definition under signal.

Conversation history

These tools require can_read_history and read shared conversations only. Private conversations remain excluded. Results are historical evidence; verify claims about current application state against current telemetry.

search_meta_agent_conversations

Optional arguments are literal case-insensitive query (up to 256 characters, without control characters), exclusive RFC 3339 creation-time before, offset (up to 10000), and limit (1–50, default 10).

Returns bounded conversation previews and IDs under result. Preserve before and use next_offset to continue the same search.

read_meta_agent_conversation

Requires conversation_id. Optional message offset accepts up to 10000 and limit accepts 1–20, default 10. Messages are returned oldest first. text_offset defaults to 0 and accepts up to 1000000; text_limit accepts 1–4000 characters per message, default 2000.

Returns recorded messages with turn IDs, event sequences, states and timestamps under result. Follow message next_offset values. For a long message, request its message offset with limit: 1 and follow next_text_offset. Cite the conversation, turn and message sequence when referring to its evidence.

Coding handoffs

These tools require can_coding_handoffs. Ownership belongs to the claiming MCP credential. See Coding handoffs for the human workflow.

claim_handoff

Requires handoff_id and agent_name (1–100 nonblank characters). Returns the prepared task, prompt and investigation context. Retrying with the same credential and display name is safe.

ask_meta_agent

Requires handoff_id, question (1–20000 nonblank characters) and client_request_id (1–200 characters). Returns a durable request_id immediately. Reuse the same client request ID and question when retrying.

Questions use the connections and effective permissions of the participant who prepared the handoff, independently of the client’s history capability. Questions needing interactive approval fail with a reason. A question times out after 15 minutes.

get_meta_agent_response

Requires request_id. Returns the request state: pending, completed with its response, or failed with an error. Repeated reads do not add activity-log entries.

complete_handoff

Requires handoff_id, status (completed or failed) and a nonblank Markdown summary up to 60000 characters. Reports the terminal outcome and ends unanswered questions. Exact retries must use the same status and summary; no further work can be recorded after completion.

Structured queries

query.source

agent_runs selects identified top-level agent runs. Group queries can also use spans. The default is agent_runs.

query.time_range

An object with RFC 3339 from and to timestamps. The lower bound is inclusive and the upper bound exclusive. Required unless both top-level receive-time bounds are supplied. A discovery start-time window can span at most 30 days.

query.conditions

An optional array of structured conditions. Use kind: “intrinsic” with field for built-in fields, or kind: “attribute” with key for telemetry attributes. Equality preserves JSON types.

query.search

An optional literal substring across identities, names, statuses and attribute values. It defaults to an empty string.

query.group_by

Required by find_groups: a trace grouping or an attribute grouping as shown above.

limit and cursor

Discovery defaults to 20 results and accepts 1–100. Group inspection defaults to 50 spans and accepts 1–200. Follow next_cursor with the same query or selection and time bounds.

Receive-time discovery

find_traces accepts received_after and received_before as top-level arguments alongside from and to. For find_agent_runs and find_groups, these are also top-level arguments alongside query, not fields inside query. All receive-time bounds use RFC 3339 timestamps. Supply both bounds, at most 30 days apart, to find traces that received activity during that period. With both receive-time bounds, find_traces applies only explicitly supplied from/to start-time restrictions; omitted bounds do not default to the last 30 days. For find_agent_runs and find_groups, query.time_range is optional only when both receive-time bounds are supplied.

Receive time helps find new activity added to an older trace. It selects candidate traces or groups, not the span membership to inspect. inspect_group still requires explicit started_after and started_before bounds covering the group’s execution.