Skip to main content
This page is the published copy of the operating guide that ships with the tool as AGENTS.md — in the release archive and in getsynq/synq-scout. It is deliberately denser than the rest of this section. See MCP for the hosted server and its tool tables, and the CLI reference for every flag.
This is the operating guide for a coding agent using synq-scout: what it can do, how to reach it, which command to pick, and the mistakes that waste a session. It is written to be acted on top-down. Scout is an agent over your data estate. It answers questions about your warehouse and your Coalesce Quality workspace — what an asset is, what changed, what broke and why, what to test — and it can act: set an issue’s status, comment, open an incident, author monitors and tests. Every capability is a tool, and the same tool set backs all three ways of running it. Scout only ever connects outward, so it can run inside your network with nothing exposed.

​
1. Pick the right surface

Three ways in. The first is almost always the right answer. 1. The hosted MCP server — no install. Scout’s tools are served over MCP at a URL, so an MCP client (Claude Code, Cursor, Claude Desktop) can use them with nothing running on your side. If your goal is “let my agent query the estate”, stop here — you do not need this binary at all. 2. synq-scout mcp — the same tools, served locally. Use this when the data must not leave your network, or when you need warehouse tools that query your databases directly with credentials you hold. It speaks MCP over stdio, so point your client at the command rather than a URL:
3. synq-scout tools — one tool, one command, no client. The fastest way to answer a single question, and the only surface where you can see a tool’s exact schema. Start here when exploring what Scout can do. synq-scout agent is the fourth mode: long-lived, picking up triage work from your workspace on its own. It is a deployment, not something you drive — see the installation notes that ship beside this guide.

​
2. Authenticate, and confirm what you are pointed at

Scout takes the first credential it finds:
  1. QUALITY_CLIENT_ID + QUALITY_CLIENT_SECRET — for servers and containers.
  2. QUALITY_TOKEN — an st-… API token.
  3. A browser login, cached under ~/.synq/oauth/.
Read auth whoami before anything that writes. It is the only thing that tells you which workspace a mutation will land in. auth status shows every stored credential across regions, auth token prints a fresh access token for scripting, auth logout removes one. If your workspace is not in the EU, pass --region us (or au), or set QUALITY_REGION. It works on every command, not just auth, and a successful login is remembered — so later commands need no flag. Then confirm the whole setup at once:
This checks the API, the model endpoint and every configured warehouse connection. Run it before blaming a tool for failing.

​
3. The loop

1. Find the tool. Do not guess a tool name; the list is derived from the build you have.
2. Read its schema before calling it.
describe prints the arguments, which are required, and the enum values a field accepts. This is cheaper than a failed call and far cheaper than a wrong one. 3. Call it.
Flags are derived from the schema: issueId becomes --issue-id, a string array becomes a repeatable flag, and anything nested takes JSON. For a deeply nested argument, pass the whole payload instead:
4. Read the response, then follow where it points. Tool responses carry a tool_usage_guidance field when there is an obvious next step — it names the specific follow-up tool and the argument to carry over. Follow it rather than guessing, and rather than re-running the same list with tweaked filters.

​
4. Never do these

  • Do not call a tool without describe-ing it first. Argument names are derived from a schema, not from convention, and a plausible guess usually fails.
  • Do not self-confirm a gated write. Tools that would reset a check’s baseline, overwrite something the UI owns, or delete a resource return requires_user_confirmation with a list of ids, and apply nothing. Those ids are a human authorization. Surface the impact, get a person to agree, then re-send with the confirmation. Passing the ids straight back because you saw them in the response defeats the entire mechanism.
  • Do not treat an empty result as “no data”. Scout returns an explicit “no results for <filter>” rather than an empty list. If you got that message, the filter is the problem, not the estate.
  • Do not parse an id out of a handle. Some responses intern a repeated sub-record into a table with short handles. Handles are local to that one response — never pass one back as an argument, and never assume it means anything next time.
  • Do not assume a write happened under --dry-run. See below.

​
5. Dry run: the default differs per surface

synq-scout tools defaults to --dry-run=true. Read calls pass through normally; a write call returns its optimistic response but nothing reaches the backend. That makes exploring safe, and it makes “I ran the tool and nothing changed” the expected outcome rather than a bug.
The response says so explicitly when a mutation was dropped. mcp and agent default to --dry-run=false, because a client driving them expects writes to land.

​
6. Reading the output

-o selects the format: json (default), yaml, or toon — a compact tabular encoding that costs far fewer tokens on repeated records.
Logs never contaminate the payload. Under tools, auth and shell completion, logs go to stderr and stdout carries only the result, so synq-scout tools … -o json | jq is safe. Set LOG_LEVEL=DEBUG when a call fails for no visible reason; LOG_FORMAT=text makes that readable. Responses are shaped for an agent, not a UI: list rows carry a few load-bearing fields, with include_* arguments to ask for more. Counts and breakdowns are pre-computed, so do not make a second call to total something up. Long text is truncated with its original size and how to fetch the rest — never silently cut.

​
7. Warehouse tools need connections; most tools do not

Anything answerable from your Coalesce Quality workspace works with no configuration at all. Tools that query your warehouses directly — column profiling, value sampling — need those connections declared in agent.yaml, and say so plainly (“no direct database connections are available”) when they are missing. That message means configuration, not breakage. The example configuration that ships beside this guide is the starting point, and your workspace can generate the connection blocks for you, already carrying the right connection ids, from Settings → Scout. The field-by-field reference is the published schema, and it is authoritative in a way prose is not — read it rather than inferring field names. The example carries a yaml-language-server line pointing at the same schema, so an editor validates the file as you write it. agent.yaml is optional. A missing file is not an error.

​
8. What each thing costs

  • tools list / describe — free. No credentials needed, no backend call; tool metadata is built locally.
  • A read tool — one API call. Cheap, but a list with include_* toggles on can return a lot; prefer the default shape and widen deliberately.
  • A warehouse tool (profile_columns, sample_column_values) — a real query against your warehouse, billed by your warehouse. Scope it before running it broadly.
  • mcp / agent — the model calls are the cost, against whichever provider your endpoint fronts. Scout never picks a provider for you.

​
9. When something fails

synq-scout health distinguishes “Scout is broken” from “Scout cannot reach something”, which is the more common case.