# Starter Edition Features Starter Edition exposes ADI's control plane through a set of MCP tools that take you from discovering what the server allows, through authoring and validating a contract, to generating contract-governed SQL with full provenance. > [!NOTE] > **The Beta tool set (t1).** At t1 the enabled tools are `adi.get_capabilities`, `adi.get_authoring_spec`, `adi.generate_query`, and `adi.validate`. Execution (`adi.execute_sql`), warehouse introspection and profiling, and self-check replay are not part of t1; they belong to the execution tiers. The contract version is `1.0` and the query-request version is `1`. ## MCP tools ### adi.get_capabilities **Purpose:** Discover the active trust tier, the enabled features, and the tools you can call. **Returns:** the trust tier (for example `t0` or `t1`), a `features` object (including whether SQL execution is enabled), and the list of enabled tools. **When to use:** At the start of every session, before doing anything else. ### adi.get_authoring_spec **Purpose:** Fetch ADI's canonical contract schema and authoring guidance, including the mapping from a database engine to the SQL dialect the contract should declare. **When to use:** Before authoring a contract for your own data, so the contract you write matches the schema `adi.validate` checks against. ### adi.validate **Purpose:** Machine-validate a contract bundle against the canonical schema. **Parameters:** the contract `bundle` (the contract documents) and the `checks` to run (`structure`, `semantic`). **Returns:** whether the contract is valid, and, where it is not, path-pointed errors telling you exactly which field to fix. **When to use:** On every contract before you rely on it. Validation catches real errors that pass a manual review, including subtle ones that silently drop a join or a set of rows. > [!NOTE] > **What validation covers at t1.** At t1, `adi.validate` runs structural and semantic checks. Full warehouse-tier validation (checking the contract against your real schema, currency handling, and policies) needs server-side warehouse access, which is not part of t1; it belongs to the execution tiers. A clean result at t1 confirms the contract is well-formed, not that it matches your warehouse. ### adi.generate_query **Purpose:** Compile a structured request into contract-governed SQL. **Parameters:** a `query_request` (the metrics, group-bys, filters, ordering, and any top-N) and the `contract` it applies to, referenced either by its full documents or by a `contract_hash` returned from an earlier call. **Returns on success:** the generated `sql` and its `dialect`; `provenance` (metrics used, entities used, joins applied, group-bys, filters, and policies honoured); a plain-language `explanation`; and the row limit applied. **Returns on refusal:** a `refusal` object (see Refusals below). **When to use:** Every time a question needs answering. Guided by the Skill, your agent composes the structured request from the user's business-language question. Generation is deterministic: the same structured request returns byte-identical SQL. ### Schema and profiling tools (execution tiers) At the execution tiers, additional tools let the server read your warehouse: listing and describing tables, taking schema snapshots, and profiling tables and columns, along with `adi.replay_self_check` for replaying a contract's self-check assertions. These support contract authoring against a live warehouse. They are not part of the t1 Beta, where the server does not read your warehouse. ## The contract A contract is a bundle of YAML documents describing your data. Four are required: the top-level contract definition, the entities, the metrics, and the vocabulary (synonyms). Two are optional: policies (data classification and masking) and rules (currency handling, missing-data behaviour, and guardrails). Metrics are defined with one of four calculation types: `sum`, `count`, `count_distinct`, and `ratio` (a numerator over a denominator). Each metric declares which group-bys are allowed, which are disallowed, its default filters, its unit and currency handling, and how it is aggregated. To see a concrete example rather than working from the structure alone, ask your agent to show you the contract bundle that ships with the synthetic dataset (see Getting Started, Step 4). ## Governance features ### PII and data classification Sensitive columns are classified in the contract's policy document (for example `pii`, `sensitive`, `confidential`) with an action such as deny, mask, or redact. Grouping a metric by a disallowed column is refused before any data is touched, and safe alternatives are offered. Personal data does not reach the agent. ### Allowed and disallowed dimensions Each metric defines the group-bys that are valid for it. A request that groups by something outside that set is refused, with the allowed group-bys returned so the request can be corrected. ### Join safety The contract defines how entities relate. Guardrails can forbid many-to-many joins without a bridge table and require dimension uniqueness on a join key, so unsafe joins are refused rather than silently producing wrong numbers. ### Cardinality guardrails Grouping by a high-cardinality field can be refused, warned on, or capped, according to the contract's guardrails. Safe alternatives suggest a lower-cardinality dimension or a tighter filter. ### Read-only by default Guardrails restrict generated SQL to read verbs. Requests that would modify or delete data are refused. ## Refusals A refusal means the request was understood but cannot be fulfilled within the contract. Each refusal carries a `code`, a `message`, the `contract_path` it relates to, a `suggestion` where relevant, and a `details` object with recovery information (such as the available metrics or the allowed group-bys). Codes are lower_snake_case. | Code | Meaning | | -------------------------------- | --------------------------------------------------------------------------------------- | | `request_malformed` | The request shape or values are invalid | | `spec_version_unsupported` | The query-request version is not supported | | `metric_not_found` | The requested metric is not in the contract | | `metric_ambiguous` | The metric phrase matched more than one metric | | `entity_not_found` | An entity reference is unknown | | `field_not_in_contract` | A column is unknown on a known entity | | `dimension_not_allowed` | The group-by is not in the metric's allowed list | | `dimension_disallowed` | The group-by is explicitly blocked (for example an email column on the disallowed list) | | `policy_denied` | A policy restriction blocks the column (PII or governance) | | `join_path_absent` | The metrics cannot be safely joined (for example metrics on different base entities) | | `time_grain_unsupported` | The requested time grain is unavailable | | `aggregation_invalid` | The order-by field is not a metric or group-by | | `high_cardinality_refused` | The group-by would return too many rows | | `currency_normalization_missing` | A monetary metric has no currency conversion path | | `aggregation_fanout` | An additive metric would double-count across a to-many join | | `contract_invalid` | The contract itself cannot compile | | `contract_not_cached` | The `contract_hash` is unknown to the server; re-send the documents | | `intent_unparseable` | The request could not be interpreted | | `unsafe_operation_denied` | The requested operation is blocked | | `unsafe_sql_denied` | The SQL failed safety checks | A PII group-by is refused as `dimension_disallowed` when the column is on the metric's disallowed list, or as `policy_denied` when the column is an allowed group-by blocked by a policy action (deny, mask, or redact). Either way, personal data does not reach the agent. ## Provenance and contract reuse Every generated query returns a provenance chain: which metric definition was used, which entities and joins were involved, the group-bys and filters applied, the policies honoured, and a plain-language explanation. A `contract_hash` identifies a validated contract and can be reused on later `adi.generate_query` and `adi.validate` calls instead of resending the full documents. The Beta caches contracts for 24 hours. Because the hosted server runs multiple replicas with a per-replica cache, a reused hash can occasionally return `contract_not_cached`; when it does, re-send the contract documents and you will get the same hash back. At the execution tiers (t0 and t2), generated SQL also carries a **signature** in the form `adi-sql-v1:`, proving it was compiled from the contract, and signature-gated execution runs only signed SQL. The t1 Beta is generation-only and does not produce a signature. ## Supported platforms | Group | Platforms | | ------------------------------ | --------------------------- | | Dedicated plugins | Claude Code, Cursor, Codex | | Compatible plugins and skills | OpenClaw, Manus | **Compatible plugins and skills** covers OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification. ADI is delivered as a plugin that bundles the Skills and an MCP server, both open standards, so any MCP-compatible coding agent can integrate with ADI, through the plugin or by installing the components individually. The same logical Skill content works across platforms with only minor metadata differences.