# Dattoria MCP workflows

This guide contains detailed usage patterns. Start with `dattoria://skill.md`; load this guide only when needed.

## One report

1. Call `search_actions` with the user's request, in Russian, Kazakh, Chinese, or English. Minor typing mistakes are tolerated.
2. Call `describe_action` for the selected action ID.
3. Call `execute_action` with only the documented parameters. Use `marketplace` for analytics and pass date bounds together.
4. Read `meta.completeness`, `meta.rows`, `meta.page`, `meta.totalPages`, and `meta.warnings`. Keep the user's requested period distinct from any API defaults.

## Combine related reports

When one answer needs multiple views, discover and describe each action, then call `execute_workflow` once. Supply 1–5 ordered steps. Put only genuinely shared marketplace/date filters in `defaults`. A step can override any inherited value. Each step is checked against its own action schema before the server calls the Products API.

Example input shape:

```json
{
  "defaults": {
    "marketplace": "kaspi",
    "dateFrom": "2026-09-01",
    "dateTo": "2026-09-30"
  },
  "steps": [
    {
      "actionId": "categories.search",
      "arguments": {"search": "smartphones", "page": 1, "limit": 20}
    },
    {
      "actionId": "categories.products",
      "arguments": {"categoryName": "Phones", "search": "smartphones", "page": 1, "limit": 20}
    }
  ],
  "continueOnError": true
}
```

The sample category path is illustrative; resolve real names from returned data rather than copying it blindly. A workflow is sequential and is not a transaction. If one step fails and `continueOnError` is true, successful steps remain in the result and the overall status is `partial`.

## Search across languages

Action discovery accepts localized terms, but data search terms may be marketplace-language-specific. For actions that document `searchAlias`, pass the original phrase as `search` and one translated phrase as `searchAlias`. The response contains two separate result envelopes. Compare those result sets explicitly; do not combine row counts or claim deduplication.

## Pagination and completeness

- Start with `page: 1` and a modest `limit`.
- If metadata says `partial`, request the next page only if the answer needs it. Keep all filters and change only `page`.
- If completeness is `unknown`, the source did not provide enough evidence. Do not infer that the first page is the full result.
- A later page does not include earlier pages. Explain which page or pages support the conclusion.
- An empty result is valid evidence that no rows matched those filters; it is not automatically a loading failure.

## Exports

Set `outputFormat` on `execute_workflow` to `json` or `csv`. The tool returns a temporary download URL that expires after 15 minutes. A single successful CSV step produces a CSV file. Multiple successful steps produce a ZIP with one CSV per step and a workflow manifest. The server does not silently fetch more pages; the export contains only the requested bounded page from each step. Tell the user when a workflow is partial or a step failed.

## Error handling and limits

Unknown actions and fields are rejected before data access. Each workflow is limited to five steps, each result to 5 MiB, each date range to 180 days, and each page to the action's described limit. Rate, tariff, scope, storage, and data-service errors are authoritative. Do not retry through another key, user, endpoint, or direct database connection. Narrow the request or report the blocker.

Before running analytics, read the live `rateLimits` returned by `search_actions` or `describe_action`. Each underlying action call consumes the limits, including each workflow step and each separate original/translated search request. Discovery calls do not consume them. The returned policy version and values are authoritative; stop after a rate/load denial instead of retrying around it.

## Answering from results

State the marketplace and date range, distinguish source values from calculations, and cite the action/filters in plain language. Do not invent missing fields, freshness, totals, or causal explanations. If comparing separate reports, ensure they use compatible filters and periods before calculating a difference.