What it does
The Get Conversations tool lets agents work with conversation history on the platform: find past conversations, search across them, and read full transcripts. By default an agent sees only the conversations of the user it is working on behalf of; organization admins can widen the scope to every user’s conversations in the org. Because transcripts can be very large, the tool never returns them inline. Theget action exports a conversation as a markdown file attachment, and the agent reads it in chunks with the Read File tool — so even multi-hour, tool-heavy threads can be reviewed without overwhelming the model’s context. Enabling this tool automatically adds read_file to the agent.
Key features
- List and filter: Browse conversations by agent, user (admin only), source (chat, scheduled task, email, voice), and date range
- Full-text search: Weighted search across conversation names and message content, with highlighted snippets
- Chunked transcript reading: Full transcripts — including tool calls and their inputs/outputs — exported as attachments and read page by page
- Admin org-wide scope: With
scope: "org", admins can review any user’s conversations, with user attribution on every result - Safe by construction: Images and large binary payloads are replaced with compact markers so transcripts stay small
Parameters
Org-wide scope is verified, not configured.
scope: "org" checks the requesting user’s current role in Clerk on every call — it works for real org admins only, including in scheduled tasks and agent-to-agent calls, and cannot be enabled for non-admins. Admins can additionally hard-disable org scope on a specific agent by setting orgWideAccess: false in the tool’s config.Common use cases
Reviewing how an agent performed
“Pull up my last conversation with the Deal Screener and summarize what it concluded” The agent finds the thread, exports the transcript, and reads through it — including every tool call the other agent made.Org usage pulse checks (admins)
“How is the team actually using our agents this week? Review a few recent conversations and tell me what’s working” With org scope, the agent lists recent conversations across all users, picks representative threads, and reports on usage patterns, agent quality, and stuck workflows.Improving agents from real conversations
“Look at the last five conversations users had with the Support agent and suggest system-prompt improvements” Pairs naturally with Manage Agents: review real transcripts, identify recurring corrections or failures, then update the agent’s configuration.Checking on scheduled automations
“Did the nightly dashboard refresh actually run correctly this week?” Filter bysource: "scheduled-task", export a run’s transcript, and verify what the automation actually did — not just whether it reported success.
Reading exported transcripts
Theget action returns a short preview plus a file attachment named conversation_<id>.md. Read it with the Read File tool:
offset (a 1-based line number) to continue through longer transcripts. The transcript header includes the conversation’s metadata, token totals, and any sub-conversations spawned from it, which can be exported with further get calls.
Security
- Non-admins can never see other users’ conversations — not by thread ID, not via filters. Requests for another user’s thread return “not found.”
- The org-admin check is a live lookup against the user’s current role, so it cannot be spoofed through scheduled tasks or agent-to-agent hops, and access ends immediately when a user loses the admin role.
- Results in
minescope contain no other users’ identity fields; org-scope results attribute each conversation to its user. - System prompts are not included in exported transcripts.