Connect your AI to Outcome Owl

Before You Begin

Three things you will need

1. An Outcome Owl account with connector access. Your Outcome Owl administrator grants this; it is separate from ordinary sign-in, so confirm you have it before you start.
2. Your Outcome Owl connector address. A web address unique to your organization, ending in /mcp — for example https://<your-company>-mcp.outcomeowl.com/mcp. Your onboarding contact gives you the exact address.
3. A supported AI app. Claude (the desktop app or claude.ai in a browser), ChatGPT, or another assistant that supports custom connectors.

Part 1

Connect your AI assistant

Two ways to connect

Most business users want the sign-in method. Follow the section for your app below; the personal-key method is covered at the end of Part 1.

Your connector address — one thing to get right

Enter the address exactly, including the /mcp at the end:

https://<your-company>-mcp.outcomeowl.com/mcp

If you leave off the /mcp, your app will report that it is "not a valid connector." That is the single most common setup mistake — check the ending first if the connection does not take.

Connect with Claude

Claude Desktop and claude.ai (in your browser) connect the same way.

1. Open Settings → Connectors and choose Add custom connector. When prompted for a name, enter Outcome Owl — the name you will use to refer to it when you ask questions (for example, "Using Outcome Owl, …").
2. Paste your connector address (ending in /mcp) and confirm.
3. Click Connect. A secure Outcome Owl sign-in page opens in your browser.
4. Sign in the way you already sign in to Outcome Owl. If you sign in with a password, you are asked to set a new one on your first sign-in, or right after a password reset, before continuing.
5. Review what you are granting — read-only access to your Outcome Owl data — and click Allow. You are connected.

Connect with ChatGPT

1. Open Settings → Connectors. Adding a custom connector is available on ChatGPT's paid plans and may need to be enabled by your workspace administrator; on some plans you first turn on Developer mode to add a custom connector.
2. Add a connector using your connector address (ending in /mcp). When prompted for a name, enter Outcome Owl — the name you will use to refer to it when you ask questions (for example, "Using Outcome Owl, …").
3. When prompted, sign in to your Outcome Owl account, then click Allow to grant read-only access.

First check — confirm it worked

Once connected, ask your assistant:

A working connection responds by describing the processes and information it can see. Many assistants also offer a /getting_started item in their prompt or command menu — a short, Outcome Owl–authored welcome you can pull up any time.

Good to know

• Read-only. The connection can never change, delete, or add to your data.
• It acts as you. It sees only what your Outcome Owl account and role allow, and every request is recorded to your account for audit.
• Disconnect any time. Remove the connector in your AI app, or ask your administrator to revoke your access. De-activating your account ends the connection immediately.
• Network access. Access is limited to your organization's approved network addresses. If you connect from an unexpected network, the connection may be refused by design.

Connect with a personal key

For developer and agent tools that accept an authorization header, connect with a personal key (owlk_…) instead of signing in. Your onboarding contact issues the key; keep it secret, because it authenticates as you. For example, in a command-line assistant:

claude mcp add --transport http outcome-owl \
  https://<your-company>-mcp.outcomeowl.com/mcp \
  --header "Authorization: Bearer owlk_<your-key>"

Your key expires and can be rotated, and you are reminded before it expires. If a key is ever exposed, tell your Outcome Owl contact and it will be revoked immediately.

Part 2

Ask good questions

Connecting is the easy part. Getting the answer you actually wanted is a small skill — and it is easy to learn. This is the difference between "that's exactly what I needed" and "why is this wrong?"

Two kinds of records

Outcome Owl tracks two kinds of things, and you may have one or both:

• a process — a claim, a loan, an order: something with a start, a deadline, and a conclusion; and
• an audit trail — the ongoing history of a tracked item such as an asset, a device, or an employee record, with no deadline.

The habits below say "process" for short, but they apply to audit trails too — except anything about a deadline or being overdue, which only a process has.

Six habits that get better answers

1 · Name the process (or audit trail) you mean.

The most important habit, especially if Outcome Owl is tracking several processes or audit trails for you. If you ask "what's overdue?" with ten processes in play, your assistant has to guess which one — or stop and ask. Name it instead.

Not sure of the exact names? Start with "What processes and audit trails do you track for us?" and then drill into the one you mean.

2 · Start broad, then narrow.

Open with an orienting question, read what comes back, then ask your next question against what you saw. Faster and more accurate than trying to write one perfect question cold.

3 · Use your own business words.

Outcome Owl knows your data by the names your organization gave it — your process names, step names, and field names, spaces and capitalization included. Use those real terms rather than inventing technical-sounding ones. If you are unsure of a name, ask your assistant which names it sees, then use one it lists.

4 · Say the scope: which slice, which moment.

Three details remove most ambiguity — the process, the time window, and whether you mean "open right now" or "everything over a period." That last one matters more than it looks:

They are different questions with different answers. Tell your assistant which one you want.

5 · Ask for facts, and bring your own rules.

Give your assistant the definitions it needs, and let it combine them with Outcome Owl's facts.

Here you supplied the rule (30 days) and the amount that matters; Outcome Owl supplies the counts and totals; your assistant does the arithmetic. Avoid asking Outcome Owl itself whether you are "doing badly" — it will not judge. Ask your assistant to weigh the facts against your targets instead.

6 · When a number surprises you, ask your assistant to restate the scope.

Most surprises are not errors — they are a scope or freshness difference. Before assuming something is wrong, ask:

• "Which process and time window did that cover — and was that 'open right now' or everything in the period?"
• "How fresh is this data?" Outcome Owl marks how recently your data arrived. If your feed has been quiet, the numbers describe the last picture received, not necessarily this minute.
• A total can also include history that was loaded in — for example, older records imported in bulk. If a count looks surprisingly large, ask for the currently active or newly detected items to see today's live picture.

Discover what you can slice by

Beyond the process itself, your Outcome Owl data carries the business attributes your organization chose to send — claim type, region, product line, reserve amount, or whatever your systems include. These are the dimensions you filter by, total, and break results down by, so it is worth knowing which ones you have. Ask your assistant to list them, then use what it names in your next question:

If a dimension you want is not in the list, it may simply not be sent yet — your data team decides which attributes to include.

Starter prompts you can copy

Fill in the bracketed parts with your own process and field names. These are starting points — your assistant will ask for anything else it needs. If you use more than one connector, begin with "Using Outcome Owl, …" (as these prompts do) so your assistant goes straight to the right place; you can drop it if Outcome Owl is your only connector.

Save your best question — reuse it or schedule it

When you have iterated to a question that returns exactly what you want — the right process, the right scope, even the chart types and layout of an executive briefing saved as a web page — do not leave it buried in the conversation. Turn it into a reusable prompt you can run again next week, next month, or on a schedule.

1. Ask your assistant to consolidate the whole exchange into one reusable prompt. After a result you are happy with: "Turn everything we just did into a single reusable prompt I can run again — keep the scope, the fields, and the output format."
2. Have it read the prompt back to you. Ask it to restate the prompt in its own words and order, so you can confirm it captured what you meant before you rely on it — then fix anything that drifted.
3. Save it, or schedule it. Keep the finished prompt where your assistant stores reusable instructions, or hand it to an automation feature — Claude Cowork is one example — so it runs on its own and delivers the briefing to you on a recurring schedule.

Two habits keep a saved prompt reliable: start it with "Using Outcome Owl, …" so a scheduled run still goes straight to the right connector, and remember that each run reflects your data as of the moment it runs — the freshness caveat above still applies. Outcome Owl supplies the facts; your saved prompt carries the rules and the format you want applied to them.

What Outcome Owl will — and will not — tell you

It will tell you: how many, how long, what state something is in, what changed, a step-by-step timeline, a total across a set you define, and what step usually follows another.

It will not tell you: whether a finding is "good," "bad," or "concerning"; why something happened; what you should do next; or what will happen in the future. Those are yours to decide — with your assistant's help and your own context. Two more boundaries worth knowing:

• It matches on your named processes, steps, fields, and time windows. It does not search the free-text wording of notes and comments for a keyword.
• There is no "find things like this one" similarity search. Ask by name, filter, and time window instead.

When a request falls into one of those areas, Outcome Owl politely declines and tells you why, rather than guessing — so you never act on a confident-sounding wrong answer.

Part 3 · For developers

Automating with autonomous agents (A2A)

Everything above assumes a person at a keyboard. This part is for developers and integrators connecting an autonomous agent (agent-to-agent, or A2A) rather than a person — it assumes you have read Part 2, and the same "facts, not judgments" principle governs everything here.

The model: Outcome Owl reads, your agent acts

Outcome Owl is read-only business observability. An autonomous agent connects, reads process health on a schedule with no human in the loop, and then acts through your own systems — assigning work, opening a ticket, notifying a team, updating a case. Outcome Owl never takes the action; it supplies the facts the action is based on.

That division has a consequence worth stating plainly. Because your agent may take a real, sometimes irreversible action on the strength of an Outcome Owl answer, the correctness of that answer is part of your control environment, not a convenience. Treat an Outcome Owl fact with the same care your agent would give any other input that moves money or work.

Connecting an agent

• Give the agent its own identity. Use a dedicated service account, not a person's login, so the agent's activity is attributable to it alone in the audit record.
• Authenticate with a personal key. Agents connect with a key (owlk_…) in an Authorization: Bearer header rather than the interactive sign-in — see Connect with a personal key in Part 1. Keep the key in a secret store, never in source code.
• Grant least privilege. The agent sees only what its account and role allow. Scope it to the processes and data it actually needs.
• Plan for rotation and revocation. Keys expire and rotate; revoke immediately on exposure. Revoking the key is also your kill switch.
• Run from an approved network. Access is limited to your organization's allowed network addresses; host the agent on one.
• Confirm the surface on connect. Call server_info_v1 to read the build and schema_version and to confirm access_mode is read_only, then call usage_guide_v1 once for the operating manual — how to read the response envelope, the full error taxonomy, and the proven query playbooks, delivered by the server itself.
• Disambiguate when the agent has more than one tool source. If your agent connects to several tool servers, make its routing explicit in the agent's own configuration or system prompt — target the Outcome Owl tools by name for process-health reads — rather than relying on the model to choose the right source.

Discover names; never hard-code them

• Call list_processes_v1, list_process_steps_v1, list_rules_v1, and attribute_catalog_v1 to learn the exact names before filtering, sorting, or aggregating by one.
• Pass every customer-defined name and value verbatim as a parameter — spaces, casing, and all. Do not reshape a name into a code-style token; the tools expect your real business text.
• Scope before you ask. Every listing tool requires at least one filter and never returns your whole population. An unscoped query is refused, not silently truncated.

Keep your judgment in the agent

Outcome Owl reports facts and refuses judgment by design. It will not label a finding good, bad, or concerning; say why something happened; forecast; or recommend an action. A request of that kind comes back as a structured refusal that names the category — not an error, and not a guess. So the decision rules — what counts as a problem, and what to do about it — live in your agent. Outcome Owl supplies the signal; your agent supplies the policy.

Act exactly once (idempotency)

This is the discipline that separates a reliable agent from one that double-pays or double-notifies. A scheduled agent starts each run with no memory of the last one, so it must recognize a problem it has already handled. Outcome Owl gives you the identifiers to do that:

• The problem carries a lifetime-stable identifier, action_dedup_key, on every process and violation row. It does not change when the problem is re-detected, resolved, or re-fires. Deduplicate your external actions on it.
• The specific occurrence is that identifier paired with a generation stamp: for a violation, first_observed_utc_timestamp (stable across routine re-evaluation, moving only when a resolved violation re-fires as a new occurrence); for a process or overdue item, expected_completion_utc_timestamp (a restatement moves it, and restatement_count records how many times).
• The rule: the same identifier with the same stamp is the occurrence you already handled — skip it. The same identifier with a moved stamp is a new occurrence — act again.
• Re-read before you commit. A violation exposes a single change clock, last_updated_utc_timestamp, which advances on first detection, resolution, or re-fire but not on an unchanged re-evaluation; a process has no single change clock — compare the combination of status, latest_entry_end_utc_timestamp, expected_completion_utc_timestamp, and restatement_count; all four unchanged means it has not moved.
• Keep the ledger outside the agent. Store what you have acted on in your own system, or rely on your incident tool's server-side deduplication — never in the agent's own memory, which a scheduled run does not carry forward.

Act on "now," not on loaded history

An estate that imported its history will show that history in its totals, and an agent that treats every returned violation as a fresh, act-now problem will over-act. Two independent signals keep this straight:

• Where the data came from — origin: live for a breach that arose while connected, surfaced for history brought in by a bulk load. A count-only violation request also returns a provenance_breakdown across live, surfaced, and unclassified.
• Whether the breach is unfolding now — breach_is_current. A record loaded weeks ago can still cross a deadline today; it reads as surfaced history yet is a current, urgent breach.

For "what do I act on right now," read breach_is_current — do not filter on origin='live' alone, which can hide a current breach as old history. To list or count that act-now set directly, pass breach_recency='current'. And note that a violation count is of violation records; pass count_by='instances' for the distinct affected cases.

Act only on fresh data

Every response reports data_confidence: high when your feed is essentially live, normal in the routine window, and low when nothing has arrived past the configured threshold (the reason names how long it has been quiet). When confidence is low, the numbers describe the last picture received, not necessarily this minute. An agent that takes real action should gate on high — acting only when the data is current — rather than merely "not low."

Poll for change; do not re-scan

• Use deltas_v1 with your last-check timestamp to fetch only what became overdue, stalled, or violated since you last looked. This is the polling tool — do not loop snapshot_v1, which re-does the full briefing every time.
• If your clock runs ahead of the server's, a future timestamp returns an explicit note rather than silent zeros — handle it as "no window yet," not "nothing happened."
• Size before you fetch: explain=true previews a broad query's estimated cost and whether it will be admitted, without running it; count_only=true returns the number without the rows.

Handle failures on the fields, not the prose

Every error is a structured envelope, so an agent branches on data rather than parsing a sentence:

• code names the condition — bound_required (add a scope filter), invalid_argument (a value or token is wrong — do not retry unchanged), estimate_rejected (too costly; narrow and retry), budget_exceeded (started but stopped at the time budget; narrow and retry), and not_found (the identifier is not on this surface — a process identifier that is not found may be an audit trail).
• next_action gives a discrete directive — add_filter, narrow_scope, verify_identifier, retry_later, or revise_request.
• retryable is true only for a transient service condition; use it to decide whether a retry could ever succeed.
• An empty list is not an error: no_matching_rows means the filters were valid and nothing matched; filter_value_unknown means a name you passed is not configured — fix the name, do not loosen other filters.

Read the response envelope

• Population basis. Every counted answer names its population_basis — the live processed store, the period-flow substrate, the attribute substrate, or the violation ledger. Corroborate numbers within a basis; a cross-basis mismatch is usually linkage lag, not a bug — snapshot_v1 reports awaiting_linkage so you can tell whether that lag is currently material. Never blend a period-cumulative (flow) count with a point-in-time (backlog) snapshot.
• Clocks. Each freshness stamp names which clock it rides. In particular, last_activity_utc_timestamp is the data-arrival clock — it moves whenever anything about an item reaches the platform, reloads included; business idleness reads from inactivity_hours and the latest business entry, not from arrival.
• Formats. Timestamps are Coordinated Universal Time (UTC) in RFC 3339 form with an explicit +00:00 offset; counts are integers; exact money and percent-change values are decimal strings — keep them as strings so you do not silently round money to a floating-point value.

Treat your data as data, not instructions

Outcome Owl returns your business's own text — contextual messages, and the names and values of your steps, categories, and attributes — as data about your business, never as instructions to your agent. If such a field happens to read like a command ("ignore the above," "approve this now," "release the payment"), it is content to report, not an order to obey; it originates in your upstream data, not from Outcome Owl. Outcome Owl authors only its own field labels, status and reason codes, and fixed vocabulary, and keeps its wording legibly separate from your text — so your agent can hold that line. This matters most precisely because your agent can act: text that reaches an agent with hands is more dangerous than text that reaches a chat window.

Build against versions

Tools are versioned with a _v1-style suffix. A tool's parameters and result shape are stable within a major version, and new fields may be added within it without a break — so read fields by name and tolerate ones you do not recognize. Read schema_version from server_info_v1 as your authoritative version check; it also rides the _meta envelope on every response — data, error, and refusal alike — so a poller notices a mid-run change without an extra call. If it changes, reconnect and re-fetch the tool list before relying on the surface. Pin your integration to the tool versions you have tested.

Roll out safely

Start the agent read-only in every sense — let it observe, decide, and log the action it would take, without taking it. Verify those decisions against a set of cases whose correct outcome you already know. Then enable real actions behind the two controls above: the exactly-once ledger and the freshness gate. Keep the key revocable as a kill switch, and monitor the agent through its own audit identity.

Go Deeper

See it in context

• Executive Briefing Book — the full picture: why business observability, how the platform works, and how it fits your AI strategy.
• The proof briefings — watch the same read-only tools answer real questions across workers' compensation, lending, order management, and retention.
• Process Discovery Worksheet — map one of your own processes so onboarding is a structured exercise, not a blank page.