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

# Agent Context & Metadata Discovery

> How AI agents discover data schemas, connection metadata, and business context events in toorow.

To deliver accurate marketing analysis, AI agents require explicit context regarding underlying data schemas, supported metrics, and real-world business events. **toorow** provides a dual-layer context engine for agents.

***

## 1. Data Schema & Capability Context

AI agents must not guess column names or metrics. Before attempting complex queries or constructing report requests, agents inspect source capabilities using the core tool `get_source_capabilities(project_id, connection_ref_id)`.

### Dynamic Metadata Discovery

The capability descriptor returns:

* **Available Fields**: Exact physical source field IDs (`field_id`), canonical target names (`canonical_target`), data types, and semantic hints (`traffic`, `conversion`, `revenue`).
* **Report Profiles**: Supported grains (`supported_grains`), supported filter operators, row limits, and cadence bounds.
* **Constraint Repairs**: If a query combination violates source bounds, toorow returns deterministic repair actions (`unknown_report_field`, `unsupported_grain`, `unsupported_cadence`).

***

## 2. Business Context Events (`context_events`)

Marketing metric spikes or dips rarely occur in isolation. toorow allows teams and agents to register real-world **Context Events**:

```json theme={null}
{
  "event_type": "checkout_migration",
  "title": "Payment Gateway Update",
  "description": "Migrated checkout payment gateway to v2 API.",
  "event_date": "2026-07-14",
  "project_id": "my-project"
}
```

### Non-Causal Candidate Context (AD-9)

When an agent analyzes an anomaly on a given date (e.g. a 25% drop in conversions), toorow correlates performance shifts against registered context events.

<Important>
  **Non-Causal Invariant (AD-9)**: Context events are presented strictly as **candidate context**, never as definitive causal statements. Agents must avoid language asserting absolute cause (`"caused by"`, `"due to"`).
</Important>

***

## Next Steps & Cross-References

<CardGroup cols={2}>
  <Card title="Agent Tools Reference" icon="wrench" href="/agent-tools">
    Inspect FastMCP tool parameters and execution schemas.
  </Card>

  <Card title="Agent Rules" icon="scroll" href="/agent-rules">
    Review system instructions for LLM context handling.
  </Card>

  <Card title="MCP Host Integration" icon="network-wired" href="/mcp-host-integration">
    Learn how external agents query context over FastMCP.
  </Card>

  <Card title="Use Cases Library" icon="layer-group" href="/use-cases-library">
    Explore real-world context event scenarios in MCP App widgets.
  </Card>
</CardGroup>