`detect_changes`¶

Compare two time periods and detect significant changes across signals, scores, agents, drivers, dimensions, and guidance. Faster and lower-token than running two query_interactions calls and computing deltas in the LLM. Returns a ranked list of what actually changed with significance levels. Use when users ask about trends, what's different, week-over-week, or any temporal comparison.

Parameters¶

Parameter	Type	Required	Default	Description
`period`	string	yes	—	The recent/current time window. Accepts relative expressions ('last 7 days', 'this week', 'last month') or ISO date ranges ('2026-04-28 to 2026-05-04').
`baseline`	string	no	—	The comparison time window. Defaults to the same-length window immediately before `period`. Same formats as `period`.
`categories`	array	no	—	Which metric categories to compare. Defaults to all six (signals, scores, agents, drivers, dimensions, guidance).
`min_occurrences`	integer	no	`5`	Minimum occurrences in either period to include a metric. Default 5 — filters noise from rare events.
`agent_name`	string	no	—	Optional: limit the analysis to a specific agent.

Example call¶

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async with Client(
    "https://mcp.chordia.ai/mcp",
    auth=BearerAuth("YOUR_APPLICATION_KEY"),
) as client:
    result = await client.call_tool(
        "detect_changes",
        {
            "period": "..."
        },
    )
    print(result.content[0].text)
# Plus any of the 4 optional params from the table above.

In Claude Desktop, Cursor, or any MCP-aware client the same call is issued by the LLM automatically once the server is configured — see integrations.

Result¶

Success responses are JSON of the shape below. Optional fields are omitted when the underlying data isn't present.

{
  "window": {"from": "2026-05-05", "to": "2026-05-12"},
  "baseline": {"from": "2026-04-28", "to": "2026-05-05"},
  "changes": [
    {
      "category": "signal",
      "key": "empathy_acknowledged",
      "direction": "down",
      "rate_window": 0.62,
      "rate_baseline": 0.81,
      "delta": -0.19,
      "significance": 0.91,
      "humanized": "Empathy-acknowledged rate dropped from 81% to 62% week-over-week."
    }
  ],
  "count": 1
}

Auth context¶

Every call receives the connection's project_id and access_scope automatically — the caller never passes them. See Authentication & RBAC for how scope narrows results.

Errors¶

All tools return JSON. Errors are wrapped in { "error": "..." }. The most common shapes are documented in Python integration → Error shape.

detect_changes¶