Agent workflow

​

1. Pick the right surface

{
  "mcpServers": {
    "coalesce-quality": {
      "command": "synq-scout",
      "args": ["mcp"]
    }
  }
}

​

2. Authenticate, and confirm what you are pointed at

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/.

synq-scout auth login          # browser flow
synq-scout auth whoami         # who you are, which workspace, which permissions

• auth status shows every stored credential in all regions.
• auth token prints a fresh access token for scripts.
• auth logout removes a credential.
• By default a login goes to the shared slot, so one login serves every Coalesce Quality CLI on the machine. auth login --isolated gives Scout its own credential.
• The login asks only for the permissions that Scout’s tools need. If a permission is not granted, its tool is not in the MCP tool list.

synq-scout health

​

3. The loop

1. Find the tool. Do not guess a tool name: the list comes from the build you have.
   synq-scout tools list
   
2. Read its schema before you call it.
   synq-scout tools describe get_entity_details
   
   describe prints the arguments, which of them are required, and the enum values of each field. It costs less than a failed call, and much less than a wrong one.
3. Call it.
   synq-scout tools search_entities --query "orders"
   synq-scout tools get_entity_details --entity-id "<id from the search above>"
   
   The flags come from the schema: issueId becomes --issue-id, a string array becomes a repeatable flag, and a nested field takes JSON. For a deeply nested argument, send the whole payload:
   synq-scout tools save_domain --json '{"name":"Finance","definition":{...}}'
   
4. Read the response, then follow where it points. When there is an obvious next step, a response has a tool_usage_guidance field. It names the next tool and the argument to carry over. Follow it. Do not guess, and do not run the same list again with changed filters.

​

4. Never do these

• Do not call a tool before you describe it. Argument names come from a schema, not from a convention, and a plausible guess usually fails.
• Do not confirm a gated write yourself. A tool that would reset a check’s baseline, overwrite something the UI owns or delete a resource returns requires_user_confirmation with a list of ids, and applies nothing. These ids are a human authorization. Show the impact, get agreement from a person, then send the call again with the confirmation. If you send the ids back only because you saw them in the response, the protection does nothing.
• Do not read an empty result as “no data”. Scout returns an explicit “no results for <filter>” instead of an empty list. If you get that message, the filter is the problem, not the estate.
• Do not take an id from a handle. Some responses put a repeated sub-record into a table with short handles. A handle is valid only in that one response. Never send one back as an argument.
• Do not assume that a write happened under --dry-run. See §5.

​

5. Dry run: the default differs per surface

synq-scout tools set_issue_status --issue-ids <id> --status fixed                 # dropped
synq-scout tools set_issue_status --issue-ids <id> --status fixed --dry-run=false # applied

​

6. Reading the output

synq-scout tools list_open_issues -o toon

• List rows carry a few main fields. Use the include_* arguments to get more.
• Counts and breakdowns are already computed. Do not make a second call to add them up.
• Long text is truncated, with its original size and the way to get the rest. Nothing is cut without a note.

​

Ids: send back exactly what you got

​

7. Warehouse tools need connections; most tools do not

• Start from the example configuration next to this guide.
• Your workspace can generate the connection blocks, with the correct connection ids, at Settings → Scout.
• The field reference is the published schema. It is the authority on field names, so read it instead of guessing. The example has a yaml-language-server line that points at the schema, so your editor validates the file.
• agent.yaml is optional. A missing file is not an error.

​

8. What each thing costs

• tools list and describe are free. They need no credentials and make no backend call, because the tool metadata is built locally.
• A read tool makes one API call. It is cheap, but a list with include_* options can return a lot of data. Use the default shape first, and widen it only when you need to.
• A warehouse tool (profile_columns, sample_column_values) runs a real query on your warehouse, and your warehouse bills it. Limit its scope before you run it widely.
• In mcp and agent, the model calls are the cost, with the provider that your endpoint uses. Scout never selects a provider for you.
• upgrade replaces this binary with the latest release, verified against the release’s checksums.txt. upgrade --check reports what it would do and changes nothing. Neither one touches the workspace or a warehouse.
• About once a day, Scout prints a note about a newer release on stderr. It stays silent when an agent drives it, when the output is not a terminal, in CI and in a container, so the note is never in output you parse. QUALITY_NO_UPDATE_CHECK=1 turns it off.

​

9. When something fails