# Data sources

A data source is a named, queryable table of business data in this organisation.
Agents treat datasource metadata as the source of truth. Never invent slugs or
columns.

## What you get from MCP

- `list_data_sources` returns the datasources this token can see. Use filters when the
  user named a connector or entity (invoices, jobs, purchase orders).
- `get_data_source_detail` takes a `slug` and returns columns, parameters, and related
  metadata. Call this before writing WSQL.
- `get_data_source_choices` takes a `slug` and `filter_name` when a parameter needs a
  real choice list (status, location, account, and similar).

Optional arguments:

- `include_child_organisations` - roll the query up across organisations under the
  current one. Use this for franchise / multi-entity questions, not by default.
- `data_source_options` - extra options when the detail endpoint documents them.

## How to read a datasource

- **Slug**: stable identifier used in WSQL. Copy it exactly.
- **Title**: human-facing name. Useful for matching the user's words; still query by slug.
- **Columns**: human-friendly names, often Title Case with spaces (`Invoice Number`,
  `Order Total`). Preserve spelling, casing, and spaces in WSQL.
- **Parameters**: named filters the datasource supports. Do not invent parameter names.
  If a parameter has a finite set of values, load them with `get_data_source_choices`.
  `date-range` parameters use named presets (`Last 7 Days`, `This Month`, `All Time`)
  or a custom `YYYY-MM-DD - YYYY-MM-DD` string; `get_data_source_choices` lists the presets.

## Workflow

1. List datasources. Do not skip this and guess a slug from the connector brand name.
2. Shortlist from real titles and slugs.
3. Inspect each candidate.
4. Only then write WSQL (see `wink-toolbox://docs/wsql`).
5. Validate before execute.

If nothing matches, say so and ask the user which system or object they mean. Do not
fabricate a datasource that "should" exist.