Clearskies

View saved version →

---
name: ai-update-salesforce-field
description: >-
  Put one Salesforce field under AI maintenance with a clearskies workflow: after a
  relevant call, AI finds the right record, checks the transcript is actually useful,
  generates a value, and writes it to the field. Use when a RevOps user wants AI to
  automatically keep a specific SFDC field up to date from meeting content — e.g.
  "have AI keep Opportunity Next Steps updated", "auto-fill our Onboarding Next Step
  field after calls", "update a chosen SFDC field automatically after customer meetings",
  or
  when they pick a field for AI to own. Builds the call-ended → role filter → find
  record → relevance-agent → should-continue gate → generation-agent → updateSalesforce
  pattern, using two reusable field-agnostic agents with all field-specifics in the step
  messages. It proposes or drafts first and never publishes or edits a live workflow
  without explicit approval.
---

# Auto-update a Salesforce field with AI

This skill helps RevOps put **one Salesforce field under AI maintenance**. After a
qualifying call ends, the workflow finds the Salesforce record tied to the meeting's
account, scores whether the transcript is genuinely relevant to the target field,
generates the field's new value if so, and writes it back to Salesforce.

Two AI steps do the work, and both are **reusable and field-agnostic**: a **relevance
agent** and a **generation agent**. Their templates carry no field- or organization-specific
content — everything specific to a field arrives in the step `userMessage`. So the same
two agents serve every field you put under AI maintenance; only the messages change.

It is the field-specific recipe on top of the general clearskies mechanics — for node
shapes, validation, and safe publishing, defer to the **clearskies-workflow-builder**
skill and `workflow_capabilities_get`.

## Load connected-data context

Search first with `schema_search` for the target field concept and record lookup
relationship. Use the ranked matches to select candidate objects and fields, then call
`object_get_fields_schema` for the target and lookup objects before building filters or
writes. Disclose search warnings and never treat search as exhaustive proof. Use
`object_definitions_list` only when a complete configured object list is required. Always use
`object_get_fields_schema` to verify the complete target and lookup object schemas before
building the workflow.

## Operating rule

Build from the reference pattern, but **never publish or modify a live workflow until
the user explicitly approves that side effect.** Default to a proposed config, or a
draft plus a dry run. A test run (`workflow_test_run_start`) is always safe — it never
writes to Salesforce — so **always dry-run a valid *and* an invalid case before
publishing.** `workflow_validate` confirms shape and that references resolve, but it
does not prove the workflow behaves correctly at runtime.

Read [references/generic-ai-update-pattern.md](references/generic-ai-update-pattern.md)
before generating a config, prompt, or draft — it holds both reusable agent templates
and their `userMessage` templates.

## What it builds

```
trigger-1 (callEnded)
 → filter-1  role gate on meeting.attendees.UserRoleId
 → find-1    the target Salesforce record for {{meeting.accounts.Id}}
 → filter-2  require find-1.records to be non-empty
 → agent-1   reusable RELEVANCE agent (field-specifics in its userMessage)
 → filter-3  continue only if agent-1's output has should_continue: true
 → agent-2   reusable GENERATION agent (field-specifics in its userMessage)
 → updateSalesforce: write {{agent-2.output}} to the field on {{find-1.records.sfRecordId}}
```

Each line shows the node **id** (a `{{...}}` reference handle — it must stay in the
`<type>-<n>` form, e.g. `agent-1`); the ids are numbered in flow order here. Set a
descriptive `data.label` on every node (e.g. *Evaluate relevance*, *Generate field
update*, *Find target record*) — that's the human-readable name shown in the UI.

The order matters: **cheap deterministic filters run first** (role, record-exists, and
any RevOps-chosen gates), **then** the relevance agent and its `should_continue` gate,
and only then the generation agent and the write. Nothing is written unless the
transcript actually clears the relevance bar — this controls cost and prevents
low-quality or empty updates.

`callEnded` requires a filter immediately after the trigger; the role gate (`filter-1`)
satisfies that requirement while also scoping the workflow to the right people.

## Intake — what to confirm with RevOps

Ask only for what's missing. If the user names a target field and gives enough context,
infer the obvious pieces and confirm them in the proposal rather than blocking.

1. **Target field** — `sobjectType` (e.g. `Opportunity`, `Account`,
   `Custom_Object__c`), the field API name, and the human-readable label.
2. **Field semantics** — a definition; what belongs; what must *not* go in it; the
   desired output format (concise note, bullets, plain text, JSON).
3. **Record lookup** — how to find the record from the meeting (usually the target
   object's account field `isIn {{meeting.accounts.Id}}`); any exclusions (status not
   `Complete`, closed opportunities, inactive records, record type); the lookup `limit`
   (default `1`, since the write targets a single record).
4. **Deterministic filters before the AI steps** — the role gate is the baseline;
   optionally require an external attendee, a minimum duration, an account segment, an
   opportunity stage, a title pattern, an owner/role, or "not a placeholder/hold".
5. **Relevance gate** — the score threshold (default `> 3`; raise it to be stricter).
   Use the **reusable relevance agent**; put all field-specific details in its `agent-1`
   `userMessage`, not in the agent template.
6. **Agents & workflow handling** — reuse the existing reusable relevance/generation
   agents or create them (their templates are field-agnostic); the workflow name;
   whether to produce a proposed config, a validate-only check, or a created draft
   (default to a proposed config / validate-only when unsure); and a real test meeting
   id to dry-run against, if available.

## Build procedure

1. Confirm the desired output — a proposed config, a draft, or (with approval) a
   published workflow. Default to a proposed config / draft.
2. Gather the customizations above.
3. Load the reference pattern and resolve the concrete ids it needs (`sobjectType`,
   field API names, the account-lookup field, role ids/names, and the two agent ids) —
   get role ids and the account-lookup field id from an existing workflow's config
   (`workflows_list includeConfig:true`) or `object_get_fields_schema` rather than
   hardcoding or guessing them.
4. Assemble the graph in the order above. Reference the two **reusable** agents by id and
   put everything field-specific in their `userMessage`s (field label, API name,
   definition, what-belongs, exclusions, threshold for `agent-1`; plus output format and
   optional domain context for `agent-2`). Keep the agent templates field-agnostic.
5. Produce the **required fields** from the final config — at minimum:
   `meeting.id`, `meeting.accounts.Id`, `meeting.attendees.UserRoleId`,
   `find-1.records`, `find-1.records.sfRecordId`, `agent-1.output`, `agent-2.output` —
   plus any field introduced by custom filters or lookup conditions.
6. If the workflow MCP tools are available, use `workflow_capabilities_get` and
   `workflow_variables_get` to confirm shapes/variables, `workflow_validate` to check
   the graph, then `workflow_test_run_start` to dry-run. Only after approval use
   `workflows_create`/`workflows_update`, and only after explicit publish approval use
   `workflows_publish`.
7. If tools are unavailable or the user only wants a plan, output the config summary and
   the exact node/edge JSON for review.

## The relevance gate

Relevance is enforced in two nodes: the reusable **relevance agent** (`agent-1`) scores
the transcript 0–10 against the field's definition and returns JSON
(`should_continue`, `score`, `reason`, `relevant_details_found`); then **`filter-3`**
continues only when `should_continue` is true. Keep the threshold at `> 3` unless the
user wants stricter gating, and pass it — with the field definition — in the `agent-1`
`userMessage`. The agent template and both `userMessage` templates are in the reference
file.

## Review checklist

Before presenting the proposed workflow, confirm:

- The update field belongs to the **same object** returned by `find-1`.
- `updateSalesforce.field` uses `find-1.records.<Field_API_Name>` and `recordId` is
  `{{find-1.records.sfRecordId}}`.
- The reusable relevance and generation agent **templates contain no organization- or
  field-specific details** — all of that lives in the `agent-1` / `agent-2`
  `userMessage`s (field label, API name, definition, what-belongs, exclusions,
  threshold, output format).
- Each node has a descriptive `data.label` (e.g. *Evaluate relevance*, *Generate field
  update*, *Find target record*); node **ids** stay in the `<type>-<n>` form because
  `{{...}}` references depend on them.
- `filter-3` gates on `agent-1`'s `should_continue`, and it sits between the two agents.
- Deterministic filters appear **before** the relevance agent.
- `find-1.limit` is `1` (the write is single-record); if RevOps needs to update several
  records per call, wrap the update in a `loop` instead.
- Structured filter `fieldId`s (the role gate and the account lookup) are real for this
  organization — confirm them in a dry run; if `find-1` fails at runtime with `"filter field
  not found"`, switch that condition to an `aiFindPrompt`.
- Both a relevant meeting (proceeds and writes) and an irrelevant one (stops at
  `filter-3`, writes nothing) have been dry-run before any publish.
- Nothing is created or published without explicit user approval.

## Reference & helper files

- `references/generic-ai-update-pattern.md` — the node-by-node template: baseline graph,
  baseline filters, both **reusable agent templates** (relevance + generation), both
  agent `userMessage` templates, the `should_continue` filter, the `updateSalesforce`
  node, the required fields list, and the proposal output shape. Read it before
  generating anything.

Referenced files: 1

View saved version →

---
name: clearskies-workflow-builder
description: >-
  Author, edit, validate, and safely publish workflows and agents on the clearskies workflow-builder MCP (tools
  workflow_capabilities_get, workflows_create/update/publish, workflow_validate,
  workflow_variables_get, workflow_test_run_start, workflow_runs_get/list, agents_*,
  object_*). Use whenever the user wants to build, change, debug, or publish a
  clearskies workflow or agent — e.g. "make a workflow that…", "update the
  workflow that…", "why did my workflow fail", "publish this workflow" — or describes a
  scheduled/call/Salesforce-triggered automation that finds CRM records, runs an agent,
  posts Slack, sends email, or writes Salesforce, even without saying "workflow" (e.g.
  "every morning DM me my open deals"). Key rule: workflow_validate checks structure and
  references but not runtime behavior, so ALWAYS dry-run with workflow_test_run_start
  before publishing.
---

# clearskies workflow builder

Building a clearskies workflow looks easy and is full of quiet traps. The tools
happily accept configurations that validate clean and then silently misbehave at
runtime — writing to the wrong record, resolving a variable to empty string, or
finding nothing. This skill encodes the order of operations and the specific traps
so a workflow you ship actually does what the user asked.

## Load connected-data context

When object or field discovery is needed, call `schema_search` first with the workflow's
business concept. Use the ranked results only to select candidates; keep pagination
cursors with the same query and filters, disclose warnings, and call
`object_get_fields_schema` for each selected object before authoring filters or writes.
Use `object_definitions_list` only when a complete configured object list is required. For
audits, enumerate every field on each selected and related object with
`object_get_fields_schema` rather than treating search results as exhaustive.

## The golden rule

**`workflow_validate` confirms the graph is well-formed and that its references
resolve** — it rejects dangling `{{...}}` references, template paths a trigger doesn't
expose, unknown filter `fieldId`s, cycles, and a `findRecords` with no selection method
(unknown Salesforce objects come back as a warning). **What it cannot do is prove the
workflow behaves correctly at runtime:** whether a find actually returns records, that
an `updateSalesforce` targets more than the first record, that a
`{{find.records.some_field}}` projection resolves, or that a structured filter's
`fieldId` resolves on the workflow path. A `{"valid": true}` means "well-formed and
references exist," not "this works." The only trustworthy behavioral check is a **dry
run** (`workflow_test_run_start` → `workflow_runs_get`), where you read the actual
per-step inputs and outputs. Never publish on validation alone.

## Order of operations

Follow these in order. Don't skip to publishing.

1. **Read the available workflow capabilities.** Call `workflow_capabilities_get` first — node
   types, trigger types, and other options can change over time. It is the source of truth
   for shape; `references/lessons.md` is the
   source of truth for the traps it omits.
2. **Learn from a working example.** Call `workflows_list` with `includeConfig: true`
   and read a published workflow similar to the target. This is how you discover real
   filter field ids and proven node shapes — see the "field IDs" trap below.
3. **Design the graph**, applying the traps in `references/lessons.md`. Add a
   `runAgent` node only if the task needs real AI reasoning; skip it for pure data
   forwarding.
4. **Create or update as a draft** (`workflows_create` / `workflows_update`). Both
   write a draft; nothing runs until you publish. On a published workflow,
   `workflows_update` writes a pending draft and leaves the live version untouched
   until you publish. For incremental edits to an existing draft, `workflow_node_patch`
   applies an ordered batch of add/update/replace/delete node ops (wiring the edges for
   you) without resending the whole config; it's mutate-only, so still validate and
   publish afterward. Use `workflows_update` with the full configuration when you need
   parallel branches.
5. **Validate** (`workflow_validate`) and fix the per-node errors. Necessary but not
   sufficient.
6. **VALIDATE BY DRY RUN — the mandatory step.** See the next section. Do not skip
   this even if validation passed and the graph "looks obviously correct."
7. **Publish** (`workflows_publish`) only after the dry run confirms behavior. If the
   workflow references an agent, publish the agent first (`agents_publish`) — a
   workflow can't publish while pointing at an unpublished agent.

## The mandatory validation step (valid + invalid dry runs)

Validation that only runs the happy path tells you little. Prove the workflow both
*does the right thing* on good input and *visibly fails* on bad input — that
confirms your assertions actually discriminate, and it surfaces the silent-empty
and wrong-record traps that `workflow_validate` cannot.

**Safety:** `workflow_test_run_start` is **always** a dry run — it never writes to
Salesforce (write steps report `dryRun: true` and show the exact recordId/field/value
they *would* have written), and no Slack message or email is actually sent. Testing is
therefore safe by construction; you do not need any special setting to protect a test run.

`requireHumanReview` is a **production-only** control, unrelated to testing: on a
*live/published* workflow it holds the Salesforce write for a human to approve instead
of auto-applying it. Decide it by production intent — set it when you want a human in
the loop on live writes; leave it off when you want the published workflow to
auto-write. Neither of these facts — that test runs never write, and that this setting
is production-only — is stated in the tool docs, so make it explicit to whoever
inherits the workflow.

**Procedure:**

1. **Pick a real trigger input (non-scheduled triggers).** Scheduled triggers need no
   input. Call triggers (`callStarted`/`callEnded`) need a `meetingId`; record triggers
   (`salesforceRecordCreated`) need a `recordId`. **Never fabricate these ids** — query
   the MCP for real data: `workflow_trigger_records_list(workflowId)` returns valid
   candidate inputs for that workflow's trigger (meetings or records), with `search`.
   To choose deliberately, confirm which candidates satisfy vs. violate your
   workflow's filter using the object query tools (`crm_records_list`, `accounts_list`,
   `deals_list`, `events_list`/`events_search`, `object_get_fields_schema`). Testing on
   real records is what makes the dry run meaningful — a made-up id tests nothing.
2. **Run the valid case.** `workflow_test_run_start` with the chosen real input (a
   `recordId` or `meetingId` that *does* meet the workflow's condition; none for
   scheduled). Poll `workflow_runs_get <testRunId>`.
   Run traces containing emails/accounts are large (50–80 KB) and will overflow —
   **extract with `jq`, never read the whole blob** (`scripts/inspect_run.sh` does
   this for you).
   - Assert: run `status: completed`; each step `completed`; the resolved
     `inputs`/`outputs` contain **real values** — real `sfRecordId`s, non-empty
     fields, expected `count > 0`. An empty `count`, an empty `recordId`, or a
     value like `"FIELD=[]"` means a reference silently resolved to nothing.
3. **Run at least one invalid/negative case** — confirm the workflow does the right
   thing when it *shouldn't* fire or when a reference is wrong. Choose the probe by
   trigger type:
   - **Non-scheduled triggers → feed a real record/meeting that legitimately lacks the
     condition.** Don't fabricate an id and don't mangle the config — pull a genuine
     counter-example via `workflow_trigger_records_list` (+ the object query tools to
     find one that violates the filter), pass its real `recordId`/`meetingId`, and
     confirm the workflow stops at the filter / produces no action. This proves the
     gating works on real data the way production will see it.
   - **Reference integrity (any trigger)** — a **field projection off a find result**
     (`{{find-1.records.no_such_field}}`) resolves to an empty string silently:
     validation can't know a record's fields, so the run still reports success. Confirm
     it resolves to a real value, which also proves your happy-path values weren't
     accidental.
   - **Empty find** → confirm `count: 0` and that a downstream single-record
     `updateSalesforce` then errors `"resolved Salesforce record ID is empty"` (proves
     the find is actually filtering).
   - **Multi-record find feeding a bare update** (no loop) → confirm only the **first**
     record is targeted (the single-record trap).
4. **Compare against expectation and report.** State plainly what each run proved.
   Only after the valid case behaves and the invalid case fails-as-expected should
   you publish.

If a dry run contradicts your mental model, trust the trace and fix the graph —
that is the entire point of this step.

## Call triggers (`callStarted` / `callEnded`): screen out non-meetings

Calendar sync is a coarse filter. It excludes only *native* non-meeting event types
(out-of-office, focus time, working-location, birthday) and cancelled events, and it
drops events starting more than a year out. **Everything else becomes a meeting the
trigger can fire on** — including ordinary personal **holds, prep/blocks,
placeholders, "busy" entries, and declined or tentative invites.** None of those are
screened by title or availability at the trigger layer.

The consequence: a `callStarted` workflow with no real filter will fire on someone's
"Hold — do not book" or "Prep" block and spam Slack/email/Salesforce. (`callEnded` is
naturally safer — it generally won't fire for a pure hold because there's no linked,
completed call/transcript — but filter it too; don't rely on that.)

**Do not filter on "has a video-conferencing link."** It's tempting to add "has a real
Zoom/Meet/Teams link" as a quality signal, and it seems like the obvious way to reject
holds/blocks — but the `meeting.*` data a workflow can see has **no such field**.
`object_get_fields_schema(meeting)` and `workflow_variables_get` both cap out at:
`accounts`, `attendees`, `calendar_event_canonical_instance_id`,
`calendar_event_source_id`, `calendar_event_provider` (which calendar system, e.g.
Google/Outlook — not a join link), `duration_seconds`, `end_at`, `host`, `id`,
`participants`, `start_at`, `title`. The actual Zoom/Meet URL lives only in the raw
calendar event's free-text `description` (visible via `events_get_contents`), a field
workflows never receive. An `aiFilterPrompt` asked to check for a link is therefore
guessing from the title/attendees with no real signal, and it **will false-negative on
genuine, already-recorded customer calls**. If you need to reject non-calls, use
signals that are actually exposed: `duration_seconds` (a 0-duration or never-started
hold has none/very little), attendee count and `person_type`, response status, and
title text — not a conferencing-link check.

**So every call-triggered workflow needs a filter node right after the trigger that is
a real quality gate, not a rubber stamp.** (Call-triggered workflows are required to
have a filter immediately after the trigger anyway — make that requirement earn its
keep.) Decide what "a real meeting worth acting on" means for the use case, then
encode it. A good general-purpose `aiFilterPrompt` default:

```
Only proceed if this is a genuine meeting worth acting on:
- it has at least one attendee outside our own company (an external/customer domain),
- the current user has NOT declined it,
- it has a nonzero duration (duration_seconds > 0) consistent with a call that
  actually happened, and
- it is NOT a personal hold, focus/time block, prep or reminder, or placeholder
  (e.g. titles like "Hold", "Prep", "Block", "Busy", "OOO", "Placeholder", "Focus",
  "Reminder", or an empty/1-attendee event).
Otherwise stop.
```

Tighten or loosen per use case — an internal-standup digest wants the opposite of the
"external attendee" clause. Prefer `aiFilterPrompt` here because hold/prep/placeholder
detection is fuzzy and title-dependent; use a structured `filter` when you have a
crisp signal (e.g. attendee count, a known internal domain, response status) — but
never a conferencing-link check, structured or AI, since the data isn't there.

**Validate it with a real junk meeting.** This is the ideal negative case for the
mandatory validation step: use `workflow_trigger_records_list` to find a real "Hold"
/ "Prep" / calendar-block event, dry-run it, and confirm the workflow stops
at the filter. Then dry-run a real customer meeting and confirm it proceeds.

## The traps (read before building)

Full detail, with evidence, is in `references/lessons.md`. The ones that bite most:

- **Prefer `aiFilterPrompt` / `aiFindPrompt` over structured filters.** A structured
  filter's `fieldId` is finicky — it must resolve on the workflow path, and one that
  looks right can still fail at runtime with `"filter field not found"`. The AI-prompt
  forms take natural language (and interpolate `{{...}}`), sidestep field ids, and are
  the reliable default. If you must use a structured filter, copy the exact `fieldId`
  from a working workflow's config (`workflows_list includeConfig:true`) and confirm it
  in a dry run.
- **Traverse relationships by chaining finds, not by dotting the variable tree.**
  To act on records related to a prior step, add a second `findRecords` filtered
  `isIn {{find-1.records}}` (or `{{find-1.records.<field>}}` / `<relation>`), then act
  on `{{find-2.records.sfRecordId}}`. Relations resolve at runtime **even when
  `workflow_variables_get` omits them** — don't conclude "unreachable" from the
  variable tree; a dry run is the arbiter.
- **`updateSalesforce` is single-record.** `{{find.records.sfRecordId}}` targets only
  the **first** record and still reports `completed`. To update N records, wrap the
  update in a `loop` over `{{find.records}}` and use `{{loop-1.sfRecordId}}`.
- **No sub-day relative dates.** Date filters support day-granular relatives
  (`yesterday`, `{"relativeDate":"numberOfDaysAgo","value":N}`) or RFC3339 — there is
  no "last 4 hours". For short windows use an `aiFindPrompt` ("emails in the last 4
  hours"). `now-4h`-style strings are accepted silently and never work.
- **A field projection off a find result can resolve to empty silently.**
  `{{find-1.records.no_such_field}}` — or any reference that resolves to an empty
  collection — becomes `""`/`[]` at runtime with no error; for a Salesforce write that
  blanks the target field. Always confirm resolved values in the dry-run trace.
- **Use `workflow_variables_get` to confirm a `{{...}}` path exists.** It takes an
  inline configuration you're drafting *or* a saved `workflowId`, and returns a compact
  tree — direct fields as dot-path `systemFields`, related objects as drillable
  `references` (`subFields` / `drillable`) rather than a fully-expanded graph. Reference
  only paths it confirms, but remember relations resolve at runtime even before you
  drill them (see the relationship-traversal trap in `references/lessons.md`).
- **A `runAgent` summarizer may append meta-commentary** ("want me to draft a
  follow-up?") to its output, which then flows verbatim into a Slack message or
  email. If the agent's job is to produce a message body, tell its template
  explicitly to output only that text with no questions or offers of further work,
  and confirm the fix in a dry run.

## Reference & helper files

- `references/lessons.md` — the complete, evidence-backed trap list, the draft/publish
  model, trigger/node field details, known organization field ids, and worked
  valid/invalid dry-run examples. Read it before building anything non-trivial.
- `scripts/inspect_run.sh` — `bash scripts/inspect_run.sh <run-json-file>` prints the
  per-step status/errors and resolved inputs/outputs from an overflowed
  `workflow_runs_get` result without dumping the whole blob into context.

Referenced files: 2

View saved version →

---
name: use-clearskies-revenue-data
description: Query and synthesize revenue context from the clearskies MCP across connected CRM objects, accounts, contacts, deals, employees, meetings, call transcripts, and email. Use whenever a user asks to research an account or person, inspect pipeline or CRM data, prepare for or recap a meeting, find call or email evidence, or answer a revenue question from clearskies outside the workflow builder.
---

# Use clearskies revenue data

Use the available clearskies data without assuming which CRM, objects, fields, or history are connected.

## Discover schema proportionally

- When the relevant object or field is unknown, ambiguous, or cross-object, call `schema_search` with the business concept and a modest page size. Use ranked matches to select candidates, keep cursors with the same query and filters, disclose warnings, and never treat bounded results as exhaustive.
- When the object is known but its field contract is not, call `object_get_fields_schema`. Use its query-facing `fieldId` and only its declared filters, enums, relationships, and write metadata.
- When the object and field IDs have already been verified in the current task, skip schema discovery and query directly.
- Use `object_definitions_list` only for a complete configured-object inventory.
- For an audit, inspect every field on each selected primary and related object. Use `schema_search` to select those objects only when the audit scope is ambiguous.

## Choose tools

- Use `accounts_list`, `contacts_list`, `deals_list`, and `employees_list` for the standard objects.
- Use `account_get_contacts` and `account_get_deals` after identifying an account.
- Use `crm_records_list` only for custom object types returned by live schema discovery.
- Use `records_aggregate` for counts and numeric summaries. Also inspect rows when the user asks for names or examples, when anomalies or data quality matter, or during an audit. Never list pages solely to count them.
- `schema_search` can surface activity objects such as `event` even when `object_definitions_list` omits them. Call `object_get_fields_schema` with the selected activity `objectType` before using unfamiliar filters.
- Use `events_list` for chronological activity or exact filters. Use `events_search` for semantic topic search; entity filters are optional.
- Use `events_get_contents` only after selecting specific event IDs whose transcript, email body, or other content is needed.
- Use `calendar_get_upcoming` only for future calendar windows.
- When exposed, use `support_tickets_list` and `github_activities_list` for their dedicated activity types.
- When exposed, call `identity_get` to verify the signed-in user when identity matters. Prefer `ownedByMe` over manually filtering by the returned person ID.
- When available, `deep_research` starts a longer-running research job. Use it only when the user explicitly requests deep research, then follow its status tool until completion.

## Keep the high-value guardrails

- Resolve an account, contact, or employee before requesting its activity. Before attributing a quote or finding, batch-resolve every cited account, contact, and employee ID with the corresponding list tool. Keep Clearskies UUIDs, people IDs, and external CRM IDs distinct.
- Use `externalIds` for Salesforce or Gong identifiers. Prefer exact names, domains, or emails before partial matching.
- For “my” records or pipeline, set `ownedByMe: true`. If it errors, report the error; never silently remove ownership scope.
- Follow cursors when completeness matters. Do not claim completeness from a truncated page.
- Use supported relative CRM dates or RFC3339/date-only fixed values; never pass epoch numbers. For recent past activity, set explicit UTC bounds with `endTime` equal to now. Disclose any widened range.
- For calls or transcripts, start with bounded meeting filters and use the provider filter when known. A provider-linked event does not prove transcript availability: select event IDs, call `events_get_contents`, and verify transcript content before citing it. Fetch full contents only for events used in the answer.
- Before materially relying on a stored duration, age, score, rollup, or other derived field, check its population and compare it with source fields. If it is unreliable, calculate from the sources when feasible; otherwise report the supported range or limitation instead of false precision.

## Synthesize evidence

- Combine CRM state with relevant meeting, email, Slack thread, support-ticket, or GitHub-activity evidence when that improves the answer and those sources are synchronized.
- Identify the source and date of material evidence in the response.
- Distinguish these cases explicitly: no matching record, object or field not synchronized, no events in the requested period, and inaccessible or unauthenticated connector.
- Describe only what clearskies exposes. Do not infer that absent data is absent from the customer's source CRM or communication system.
- Do not use workflow-builder tools unless the user asks to create, change, test, or publish an automation.
- Obtain confirmation before any available tool action that changes CRM or workflow state.

Referenced files: 1