Hyperbound

# Tool: GetTasks Returns the current thread's active task, bounded queue of pending tasks, completed scorecard and learning-module tasks kept as drafts, initiative tasks kept as drafts or cancelled, and fresh persisted state for recently completed asset tasks in `recentAssets`. ## When to use this tool - Before changing, completing, or cancelling a task when its current state was not returned by a preceding tool call. - When the user asks what task is active or what work is queued. - After a task transition when you need to verify which queued task became active. - When the user assigns or changes the folder for a standalone scorecard that was previously kept as a draft. - When the user asks to publish a scorecard or learning module that was previously kept as a draft. - When the user asks which assets this thread created or whether a completed asset is currently draft, published, inactive, or deleted. ## When not to use this tool - When `create_agent_v2` or the immediately preceding task mutation already returned the current state. - To retrieve general completed or cancelled task history. `reopenableTasks` and the bounded `recentAssets` projection are the only completed-task exceptions. - To search tasks from another chat thread or user. ## Do's - Change one item only in the active task or the explicitly supported retained drafts in `reopenableTasks`. A `completions` batch may include the active task followed by queued tasks. - For a kept scorecard draft in `reopenableTasks`, change it only when the user explicitly assigns its folder or asks to publish. Folder completion leaves it unpublished. Completing its retained publish decision with `["publish"]` reuses an existing folder or reopens it at required folder selection. - For a kept learning-module draft in `reopenableTasks`, complete `publishDecision` with `["publish"]` to resume its existing assignee/team picker and due-date step. Use those controls instead of free-text questions. The final Publish button publishes and assigns; do not create another module or call `finalize_asset` alongside the task. - Use the returned task and item IDs exactly as provided. - Call task mutation tools only after identifying the intended active or queued task. - If the conversation and `reopenableTasks` identify one exact draft, do not search assets or ask for another publishing confirmation. - Treat a matching `recentAssets` entry as fresh persisted state. `resourceId` is the task's original asset and `currentResourceId` is its current published asset when one exists. ## Don'ts - Do not invent task or item IDs. - Do not use the single-item mutation form for a queued task. Include queued task item IDs only in an approved `completions` batch that starts with the active task. - Do not use `textsearch_assets` to rediscover a draft represented in `reopenableTasks`. - Do not repeatedly poll when no task transition is in progress. ## Examples - User: "Which bot are we working on?" → Call `get_tasks` and summarize the active task. - User: "Cancel the second queued bot." → Call `get_tasks`, identify the intended queued task, then set it to `CANCELLED` with `set_task_status`. - User: "Move the draft to Discovery." → Match the retained scorecard task in `reopenableTasks`, resolve the folder option, and complete its folder item without publishing. - User: "Publish the scorecard I just kept as a draft." → Match the retained scorecard task in `reopenableTasks` and complete its publish decision with `["publish"]`. If it has no folder, wait for the required folder task. # Flow 1. Pass the exact `threadId` returned by `createAgent`, `createLearningModule`, or `createScorecard`. 2. Call `getTasks` when the preceding call did not return the current state, the user asks what remains, or a queue transition occurred. 3. Treat `recentAssets` as the fresh persisted lifecycle state for completed creation tasks. Use it to distinguish drafts from assets already published by task completion. 4. Continue only the first outstanding user item on `active`. Queued tasks wait unless the user asks to switch. 5. For a picker, call `getTaskItemOptions`, show its labels, ask the user to choose, and stop. For a choice, show the returned poll labels and stop unless the user already made that exact choice. 6. Treat `reopenable` as completed draft tasks. For a kept Learning Module draft, reopen its `publishDecision` with `completeTaskItem` after an explicit publication request; continue its assignee and due-date steps. For a kept scorecard draft, publish later with `finalizeAsset` after an explicit request. # Guidelines ## Do - Treat the returned active task, queued tasks, reopenable tasks, recent assets, review URLs, and next actions as authoritative. - Use `setTaskStatus` to activate a queued task before completing its items. - Treat `nextActions` as conditional continuation instructions. - Preserve a saved Publish choice while completing the remaining required setup. ## Don't - Do not display thread, task, item, resource, asset, or next-action IDs. - Do not edit a queued task before activating it. - Do not infer consent from the existence of a single option. - Do not poll repeatedly when no transition is in progress. - Do not call `finalizeAsset` for an asset that `recentAssets` confirms was already published by task completion.

getTasks

# Tool: GetUserOrganizations Lists the active Hyperbound organizations available to the authenticated user. Use this when the organization context for a request needs to be selected or confirmed. ## When to use this tool - Discovering which organizations the current user can access. - Resolving a human-readable organization name, such as "HyperDemo", to the numeric `orgId` required by organization-scoped tools. - Confirming the default organization selected for the current authenticated session. - Preparing a safe `orgId` override for organization-scoped requests. ## When NOT to use this tool - Fetching organization analytics, call data, users, scorecards, agents, or performance metrics. - Guessing or fabricating organization access. Only use `orgId` values returned by this tool. ## Parameters This tool does not accept parameters. Organization membership is derived from the authenticated user. ## Result structure The response is JSON with an `organizations` array. Each organization includes: - `orgId`: Numeric organization ID to pass to organization-scoped requests. - `name`: Organization display name. - `userId`: The authenticated user's user record ID within that organization. - `userRole`: The authenticated user's role in that organization. - `isDefault`: Whether this organization is the default context for the current authenticated session. # Flow 1. Call `getUserOrganizations` without arguments to discover the user's memberships and default organization. 2. Match a requested organization name to a returned organization. 3. If the choice is unresolved, show the organization names and ask the user to choose. 4. Use the selected returned `orgId` as an override in the next organization-scoped tool call. # Guidelines ## Do - Treat membership data as authoritative for the authenticated identity. - Keep organization and user IDs as continuation data unless the user explicitly asks for an ID. ## Don't - Do not guess organization access or pass an `orgId` that was not returned by this tool. - Do not imply that listing an organization selected it or performed an organization-scoped action. - Do not use this tool for analytics, calls, users, bots, scorecards, or performance metrics.

getUserOrganizations

# Tool: List Knowledge Base Connectors Lists enabled organization connectors and the caller's authorization status, independently of asset permissions. # Flow 1. Call this when the user asks to use connected knowledge. 2. Choose exact toolkit values from the returned catalog for `researchKnowledgeBase`. 3. Reuse retained findings and sources on follow-ups; research again only when the user explicitly requests another search. # Guidelines ## Do - Use connected knowledge for general analysis as well as permitted asset work. - Load `getAssetGuidelines` separately before authoring bots or scorecards. ## Don't - Do not activate or research connectors merely because they exist. - Do not treat access to knowledge as permission to create or modify assets.

listKnowledgeBaseConnectors

# Tool: Research Knowledge Base Researches the organization's connected sources, such as Notion, Google Drive, or a custom MCP server, for general questions, analysis, or asset work. Returns a Markdown report with the sources it used. # Execution Time This tool takes anywhere from 30 seconds to 3 minutes to execute. Warn the user about the expected wait before calling it. # Flow 1. Call `listKnowledgeBaseConnectors` and choose connector values from its `connectors` list. For asset work, also load `getAssetGuidelines`. 2. Write one self-contained `task` that describes the question, relevant conversation context, and evidence needed. Include `workflowType` only for bot or scorecard work. 3. Warn the user about the expected wait, then call `researchKnowledgeBase`. 4. For `authorization_required`, present each sign-in link, wait for the user to confirm they signed in, and call the tool again with the same arguments. 5. For `completed`, answer the question or perform the permitted action with the report as context and attribute material choices to their sources. # Guidelines ## Do - Use this tool only when the user asks to use a connected source or the request clearly depends on one. - Repeat important conversation context in the task because the researcher receives only this task. - Present sign-in links as labeled links for the connector's display name. - Retain the report and sources across follow-ups. If the retained evidence is insufficient, explain the gap and ask whether to search again. ## Don't - Do not call this tool for requests the user can answer directly or that need no external material. - Do not create or update the asset before research completes when the user asked to use a connector. - Do not display toolkit values, internal IDs, or the raw research mechanics. - Do not call this tool again unless the user explicitly requests another search, refresh, or additional retrieval, or confirms sign-in after `authorization_required`.

researchKnowledgeBase

# Tool: Text Search Assets Performs fast, ranked full-text search over Hyperbound agents and scorecards. This is the default tool for quick asset lookup when one search over indexed text and filters can answer the question. It searches the asset text indexed in OpenSearch, hydrates every match from the source database under the caller's organization and permissions, and returns a bounded set of scored matches with concise snippets. ## When to use this tool - Use this tool for agent or scorecard discovery through indexed text and its supported filters. - Use it to resolve an unknown asset before acting on it. Reuse an authoritative identifier already supplied by the conversation or a successful tool result. - Find agents or scorecards by words or phrases found in their names, roles, companies, descriptions, scenarios, personal details, goals, opinions, objections, sections, criteria, or call-type text. - Discover assets when the user describes their contents rather than providing an exact ID. - Narrow full-text matches with exact indexed filters such as document type, owner, lifecycle status, call type, creation, update, or publication time, language, company, job title, gender, emotional state, scenario, assigned scorecard, generation source, public or visible state, scorecard folder, or scorecard default, editability, and builder-only state. - Use the returned `hypId` values with agent or scorecard tools after confirming the intended asset. ## When not to use this tool - Do not use it for counts, grouped counts, aggregates, joins, analytics, exhaustive enumeration, or fields that are not indexed. Results are relevance-ranked and bounded, so they cannot establish a reliable count. Use `query` for those structured database questions. - Do not use `query` merely to perform a quick text lookup of agents or scorecards that this tool can resolve directly. - Do not use it for call transcripts. Use `search_calls` for what was said during calls. - Do not treat a missing match as proof that an asset does not exist. Full-text search is relevance-ranked and bounded. - Do not invent unsupported filters or translate a structured database question into keywords. ## Search semantics - `query` is the full-text expression. Make it concise but include the distinctive terms that should appear in the asset. - Filters are exact and case-insensitive. Values within one filter are OR conditions; different filters are combined with AND. - A document with no indexed value for a supplied filter remains eligible. A filter excludes only documents whose field has a non-null value that does not match. - `documentTypes` supports `agent` and `scorecard`. Omit it to search both. - Results are ordered by OpenSearch relevance score, then creation time. - The response includes each provider-safe hydrated asset DTO with its relevance score and matching snippet. It is limited to at most 30 results. - Search scores are meaningful only within the same tool call. Do not compare scores across separate searches. ## Do's - “Find live cold-call bots that mention pricing” → call this tool with the distinctive text plus agent, status, and call-type filters. - “Which scorecards include an opening permission criterion?” → search scorecards for the described criterion and use the returned identifiers for any follow-up action. ## Don'ts - “How many scorecards does each owner have?” → use `query` for the grouped database aggregation. - “How many MEDDPIC scorecards do we have?” → use `query`; a bounded relevance search cannot establish a reliable count. - “How many scorecards exist in total?” → use `query`. - “Which MEDDPIC scorecards are assigned to agents that had calls last month?” → use `query` for the joins and call data. ## Supported exact filters ### Agents and scorecards - `documentTypes`: asset type. This filter is always strict; documents never match a different or missing type. - `ownerUserIds`: agent owner ID or scorecard creator ID. - `statuses`: agent or scorecard lifecycle status. - `callTypes`: agent call type or any scorecard call type. - `createdFrom` / `createdTo`: inclusive lower and exclusive upper creation-time bounds. - `updatedFrom` / `updatedTo`: inclusive lower and exclusive upper update-time bounds. ### Agents only - `languages`: language or locale. - `emotionalStates`: emotional state. - `genders`: `male` or `female`. - `companyNames`: company name. - `jobTitles`: job title. - `scorecardConfigIds`: assigned scorecard ID. - `scenarioNames`: scenario name. - `isPublic`: public state. - `isVisible`: visible state. - `autogenerated`: whether the agent was autogenerated. - `autogeneratedMethods`: autogeneration method. - `publishedFrom` / `publishedTo`: inclusive lower and exclusive upper publication-time bounds. ### Scorecards only - `scorecardDefaultTypes`: default scorecard type. - `scorecardFolderIds`: resource-folder ID. - `showInBotBuilderOnly`: bot-builder-only state. - `scorecardEditable`: editable state. Do not pass agent-only filters while searching only scorecards, or scorecard-only filters while searching only agents. When searching both types, a type-specific filter does not exclude the other type because that type has no value for the field. ## User-facing behavior When Kota calls this tool directly, the user sees the search conditions while it runs and the matching asset list when it completes. If `documentTypes` contains exactly one value, the result list is rendered as interactive agent or scorecard rows. Do not repeat those same assets in a Markdown table, `create_table`, `create_csv_from_sql`, or an additional asset embedding. Use prose only for interpretation or details not already represented by the result list. # Flow 1. Present matching asset names, types, and relevant snippets from the returned results. # Guidelines ## Do - Keep asset IDs as continuation arguments and link asset names using returned URLs or the URL patterns in the server instructions. ## Don't - Do not add a user-facing `ID` field unless the user explicitly asks for one. - Do not imply that search results changed, drafted, assigned, reviewed, or published an asset.

searchAssets

# Tool: SearchCalls Semantic search over call transcripts. Finds calls based on what was discussed — topics, themes, behaviors, objection types, discovery approaches — not exact keywords. Transcripts are chunked by conversational segment (general discussion, objection handling, discovery, etc.), so results return the specific portion of a call that matched, not the entire transcript. It returns 10 chunks by default; set `limit` for up to 30. ## When to use this tool - Finding calls where a specific topic, objection, or sales behavior occurred - Identifying patterns in how reps handle particular situations across multiple calls - Locating examples of good or poor performance on a specific dimension - Answering questions like "show me calls where reps struggled with pricing objections" or "find discovery calls that uncovered the decision-maker" ## When NOT to use this tool - Looking up calls by a specific user, date, score, team, or other structured attribute — use the Query tool instead - Counting calls, computing averages, or any aggregation — use the Query tool instead - Retrieving scorecard data, agent configurations, or any non-transcript data — use the Query tool instead The distinction: **SearchCalls finds calls by what was said. Query finds calls by their metadata.** Use both together when you need to find calls matching a behavioral pattern and then retrieve their structured data. For both simulated and real calls, results contain public calls and the authenticated caller's own private calls only. Never use SearchCalls to look for another user's private transcript or infer that no such private calls exist. For objection questions — pricing pushback, competitor objections, timing or budget resistance — the **primary** source is the structured objection record: `Scorecard.objections` for simulated calls and `RealCallScorecard.objections` for real ones. Query those first. They exist for every scored call, classify the objection directly, and do not depend on transcript indexing. Run SearchCalls alongside them to enrich the findings with what was actually said, but never treat an empty semantic result as evidence that no such calls exist — answer from the objection records. For deal-scoped transcript questions, use Query first to get the deal's `DealRealCall.realCallId` values, then call SearchCalls with `callType: "realCall"` and `callIds` set to those IDs. Do not run an org-wide semantic search and manually discard unrelated deals. ## Parameters - `query` (string, required): Natural language description of what was discussed. Be specific and descriptive about the topic, behavior, or concept you are looking for. - `callType` (string, optional): `"call"` for simulated AI roleplay calls, `"realCall"` for real recorded calls. Omit to search both types. - `callIds` (number[], optional): Restrict search to specific call IDs. For deal-scoped searches, first use Query to get `DealRealCall.realCallId` values for the deal, then pass those IDs here with `callType: "realCall"`. - `callerId` (number, optional): Filter by user ID of the caller/rep. - `teamId` (number, optional): Filter by team ID. - `minDuration` (number, optional): Minimum call duration in seconds. Calls under 100 seconds are excluded automatically. - `maxDuration` (number, optional): Maximum call duration in seconds. - `dateFrom` (string, optional): ISO 8601 date. Only include calls after this date. - `dateTo` (string, optional): ISO 8601 date. Only include calls before this date. Both filter real calls by when they happened (`callDate`) and simulated calls by when they ran. A real call indexed before the search index stored `callDate` is filtered by its import time instead, so check each real call's `callDate` before placing it in a range. When a dated search may have missed such calls, read the IDs of the real calls in the range with Query on `RealCall."callDate"` and search them by `callIds` without `dateFrom` or `dateTo`. ## Query quality Search quality depends entirely on how you phrase the `query` parameter. This is semantic search — it matches on meaning, not keywords. **Good queries** — descriptive, specific about the behavior or topic: - `"rep handling pricing objection by reframing value"` - `"discovery questions about decision-making process and stakeholders"` - `"prospect expressing urgency about implementation timeline"` - `"rep failing to ask follow-up questions after prospect mentions a pain point"` **Bad queries** — vague, keyword-like, or too broad: - `"pricing"` — too vague, will match any mention of price - `"good call"` — not a searchable concept - `"John's calls"` — use the callerId filter or Query tool instead - `"calls from last week"` — use dateFrom/dateTo filters or Query tool instead When analyzing patterns across calls, run multiple focused searches rather than one broad search. For example, to understand how a team handles objections, search separately for `"handling budget objection"`, `"handling competitor objection"`, and `"handling timeline objection"` rather than a single search for `"objection handling"`. ## Result structure Each provider-safe result contains the hydrated call data below. Provider IDs, provider names, provider configuration, provider metadata, and provider-related columns are omitted. - **Call metadata** — ID, type (simulated/real), creation date, duration, caller name. A real call's `createdAt` is when Hyperbound imported it; date it by `callDate`, when it happened - **Simulated call details** — agent name, company name, call type - **Real call details** — title, call type - **Matched transcript chunk** — the specific segment of the conversation that matched your query - **Chunk metadata** — chunk number, start and end timestamps in seconds - **Relevance score** — how closely this chunk matched your query (higher is better) Use the call IDs from results to link to specific calls in your response. Use the timestamps to reference exact moments in the conversation. ## Working with results - Results are ranked by relevance. The top results are the strongest matches — do not treat all results as equally relevant. - Each result is a transcript **chunk**, not a full call. The same call may appear multiple times if multiple segments matched. This is expected and useful — it shows which parts of the conversation are relevant. - Read the transcript chunks carefully. Your pattern recognition and coaching value comes from understanding what was actually said, not just that a match was found. - When reporting findings, always cite the specific calls and quote or paraphrase the relevant transcript segments. Ungrounded claims like "reps generally struggle with pricing objections" are worthless without the evidence. - If results are empty or low-relevance, rephrase the query with different terminology before concluding that no relevant calls exist. The same concept can be expressed many ways. # Flow 1. Present the relevant caller or call name, date, matched evidence, and timestamp. 2. Explain that results are relevance-ranked transcript chunks rather than an exhaustive call list. # Guidelines ## Do - Use `dataAnalyst` for counts, aggregates, metadata-driven reporting, or analysis across the results. - Keep call and user IDs as continuation data unless the user explicitly asks for an ID. ## Don't - Do not turn a semantic match or empty result into an unsupported aggregate conclusion. - Do not expose provider data. Provider IDs, provider configuration, and provider-specific columns are omitted.

searchCalls

# Tool: SetTaskStatus Changes an AI chat task to `ACTIVE`, `IN_QUEUE`, `COMPLETED`, or `CANCELLED` and returns every task changed by the queue transition. The transition is atomic. Making a queued task active moves the previous active task back into the queue. Completing, cancelling, or queueing the active task promotes the oldest other queued task when one exists. ## When to use this tool - The user asks to switch to a different queued task. - The user asks to pause the active task and continue another task. - The user explicitly asks to cancel or abandon a task. - A workflow must be force-completed even though required task items remain. ## When not to use this tool - A folder, scorecard, confirmation, string, or number item needs to be completed. Use `complete_task_item`. - The final required item was just completed. The task completes automatically. - You do not know which task the user means. Call `get_tasks` or ask for clarification first. - The task is already completed or cancelled and the requested status differs. Terminal tasks cannot be reopened. ## Do's - Use the exact task ID returned by `create_agent_v2`, a task mutation, or `get_tasks`. - Use `ACTIVE` to switch control to a queued task. - Use `IN_QUEUE` to pause a task without cancelling its draft. - Use `COMPLETED` only when the workflow should end despite outstanding items. - Use `CANCELLED` only when the user explicitly wants to abandon the task. - Treat every returned task state as authoritative. ## Don'ts - Do not use `COMPLETED` to publish an asset. Publishing remains a separate action. - Do not use `CANCELLED` for a revision, review, or temporary pause. - Do not invent task IDs or assume queue order. - Do not call multiple status changes in parallel for the same thread. ## Examples - User: "Work on the renewal bot instead." → Call `get_tasks`, identify that queued task, then set it to `ACTIVE`. The previous active task returns to `IN_QUEUE`. - User: "Pause this bot for now." → Set the active task to `IN_QUEUE`; the oldest other queued task becomes active when available. - User: "Cancel the second queued bot." → Identify the exact task and set it to `CANCELLED`. - A task must end without its remaining items → Set it to `COMPLETED`, then explain any completion yield returned by the task. # Flow 1. Tell the user which named asset tasks changed and report every returned task's new state, including tasks moved back to `IN_QUEUE`. 2. Explain what a newly active task still requires. For a picker, retrieve labels, ask for an explicit choice, and stop. # Guidelines ## Do - Use `completeTaskItem` for normal folder, scorecard, confirmation, string, or number selections. - Use `COMPLETED` only when the user intends to end the workflow despite unresolved items. - Use `CANCELLED` only when the user explicitly wants to abandon the workflow. ## Don't - Do not display task, resource, thread, asset, or next-action IDs. - Do not issue parallel status changes for the same workflow. - Do not try to reopen a terminal task. - Do not imply that completing or cancelling a task published an asset.

setTaskStatus

# Tool: Switch Current Organization Makes one of the authenticated user's Hyperbound organizations current for subsequent MCP requests. Each organization may expose a different set of MCP tools based on its configuration and the user's role. Switching organizations refreshes the available tool list. # Flow 1. If the user requests an operation whose required tool is unavailable in the current organization, consider whether they intend to perform it in another organization before saying it cannot be done. 2. Call `getUserOrganizations` and identify the organization the user requested or intended for the operation. 3. If the organization is ambiguous, show the organization names and ask the user to choose. 4. Call `switchCurrentOrganization` with the exact `orgId` returned for that organization. 5. Refresh the available tools and continue only with tools exposed for the selected organization. # Guidelines ## Do - Use only an `orgId` returned by `getUserOrganizations`. - Remember that different organizations may expose different tools. - When a user-requested tool or capability is unavailable, check whether switching to the intended organization would make it available. - Tell the user which organization is now current after the tool succeeds. - Refresh the available MCP tools after switching because organizations may expose different workflows. ## Don't - Do not guess an organization ID or switch organizations without a clear user request. - Do not conclude that a requested capability is unavailable everywhere based only on the current organization's tool list. - Do not claim the switch succeeded unless this tool returns success. - Do not use this tool merely to run one operation in another organization when that tool accepts an `orgId` override.

switchCurrentOrganization

# Tool: UpdateAgent Creates or reuses the real draft for one existing persisted agent, saves the requested changes there, and returns the saved draft `AgentDto`. Use `create_agent_v2` for a new agent. This tool requires the exact published or draft agent `hypId`. ## Input contract - Include only fields that need to change. Omitted fields remain unchanged. - Do not send lifecycle status. The live agent remains unchanged until its draft is published. - Preserve grounded details that are unrelated to the requested change. - `supportingAgentInfo` replaces the complete supporting-participant list. Supply zero to three participants with names, roles, genders, emotional states, and grounded persona details. A participant's call scenario inherits the primary agent's scenario when omitted. Send an empty list to return the draft to a single-party roleplay. The tool assigns compatible voices and avatars. - Use `openerLine` for a standard roleplay opener. For a bite-sized roleplay, use `biteSizedRoleplayCallOpener` for the exact one-line opening and preserve its existing knowledge and focus unless the user asks to change them. - Set `isVisionEnabled` when the user asks to enable or disable Vision, including for a bite-sized roleplay. Preserve it otherwise. - To make a bot private, set `acceptsPrivateCalls` to `true` and `letRepsDecideCallVisibility` to `false`. Its calls and recordings then stay with each caller. - To make calls public, set both visibility fields to `false`. To let callers choose per call, set `acceptsPrivateCalls` to `false` and `letRepsDecideCallVisibility` to `true`. - Call visibility does not control who can discover the bot. Bot discoverability is a separate admin setting. - Set `hideLeaderboard` to `true` when the bot should not show a leaderboard on the pre-call or post-call page. - Set `tags` only when tags should change. It replaces the complete tag set, creates missing organization tags, and accepts an empty array to clear all tags. - Set `folderIds` only when bot folder membership should change. Pass the complete desired set of existing numeric folder IDs, preserving unrelated folder memberships. The change is saved to the draft and takes effect when published. ## Result contract - Returns the persisted before-and-after agent snapshots. Derive displayed changes from those snapshots. - Linked update drafts can be reviewed and published separately; standalone creation drafts remain governed by their existing task. - Returns the persisted draft as the source of truth. Publishing is a separate action. ## Agent quality examples These examples show the expected realism, specificity, and internal consistency of an agent configuration. They are quality references, not literal tool-call payloads. When updating an existing agent, pass its real `hypId` and only the fields that need to change. ### Example 1: Strategic sales leader ```json { "firstName": "Jane", "lastName": "Bowen", "gender": "FEMALE", "jobTitle": "Director of Sales", "personalDetails": [ "You have led the sales organization at Agile Solutions for four years after managing a regional team at a competing CRM vendor.", "You started as an account executive, so you quickly recognize whether a rep understands enterprise sales fundamentals.", "You are concise with vendors and only share internal metrics when the question has a clear business purpose." ], "companyName": "Agile Solutions", "companyDetails": [ "Agile Solutions is a Series C B2B SaaS company with approximately 100 employees.", "The company helps software teams implement and maintain agile project-management workflows.", "The company is prioritizing efficient growth after reducing its sales-technology budget by 10%." ], "companyOrgStructure": [ "You report to the Chief Revenue Officer.", "Five SDR managers report to you.", "The sales organization has approximately 50 SDRs and 50 account executives." ], "goals": [ "Increase qualified pipeline without adding headcount.", "Improve SDR ramp time from four months to three months.", "Prove measurable ROI before renewing or adding sales tools." ], "opinions": [ "You prefer Outreach over Apollo because its CRM integration and email deliverability have produced fewer operational issues for your team.", "You believe HubSpot is cost-effective, but its forecasting limits force your operations team to maintain manual reports.", "You value call coaching when it produces observable behavior change rather than generic activity metrics." ], "objections": [ "Your sales-tool budget was reduced by 10%, so any new purchase must replace an existing cost or show a short payback period.", "A previous integration corrupted CRM ownership fields, so security review and data-write controls are mandatory.", "You will not accept broad productivity claims without a pilot tied to ramp time, conversion rate, or pipeline coverage." ], "emotionalState": "nice", "callType": "discovery", "description": "A pragmatic sales leader who is open to change but demands evidence, operational safety, and clear ROI.", "language": "en-US" } ``` ### Example 2: Technically demanding engineering buyer ```json { "firstName": "Drew", "lastName": "Hader", "gender": "MALE", "jobTitle": "Observability Engineering Manager", "personalDetails": [ "You spent eight years in backend engineering, SRE, and observability before taking ownership of the on-call program.", "You are comfortable challenging vendors on architecture, security boundaries, and failure modes.", "You prefer concrete answers and become skeptical when a rep avoids implementation details." ], "companyName": "Northstar Cloud", "companyDetails": [ "Northstar Cloud operates a multi-tenant B2B platform used by enterprise engineering teams.", "The platform recently moved from a monolith to more than 60 production services.", "A recent severity-one incident exposed gaps in trace coverage and delayed root-cause analysis." ], "companyOrgStructure": [ "You report to the Vice President of Engineering.", "You manage eight observability and reliability engineers.", "Application teams own their services, while your team owns standards, shared tooling, and incident response." ], "goals": [ "Reduce mean time to detection from four minutes to under one minute.", "Cut mean time to resolution by improving trace and log correlation.", "Consolidate overlapping monitoring tools without weakening coverage." ], "opinions": [ "You believe observability products should expose predictable ingestion costs because an API failure previously caused a 35% billing spike.", "You prefer open standards such as OpenTelemetry because proprietary instrumentation increases migration risk.", "You consider reliable support part of the product after a billing issue remained unresolved for several months." ], "objections": [ "You will reject another point solution unless it replaces existing infrastructure or removes meaningful maintenance work.", "You need evidence that data residency, retention, and access controls satisfy the security team's requirements.", "You will not run a production pilot until the vendor explains rollback behavior and failure isolation." ], "emotionalState": "less_rude", "callType": "demo", "description": "A skeptical technical evaluator who rewards precise architecture, measurable reliability improvements, and operational honesty.", "language": "en-US" } ``` # Flow 1. Call `updateAgent` and treat the returned saved draft and persisted changes as authoritative. 2. For a linked update draft, follow the branch that matches the conversation: - If the user already explicitly approved publication, call `finalizeAsset` immediately. After it succeeds, tell the user exactly what was saved and published, then provide the labeled link. - Otherwise, tell the user exactly what was saved, explain that the changes are in a draft and the currently live bot is unchanged, provide the labeled review link, ask whether they want more changes or want to publish, then stop. 3. For a standalone creation draft, tell the user what was saved and provide the labeled review link, then continue its original task. Its task owns folder and scorecard setup and the Publish or Keep as draft decision; do not bypass it with `finalizeAsset` while it remains active. 4. If a standalone bot was kept as a draft and the user later asks to publish it, call `finalizeAsset` after its task is complete. # Guidelines ## Do - Apply the guidelines from `getAssetGuidelines` for workflowType `ai_roleplay_bots` to every change you author, calling it first when the conversation has not loaded them yet. - Summarize only changes that were actually persisted. - Use asset and workflow IDs only as continuation arguments. - Present `reviewUrl` as a descriptive link without printing the raw URL. - Treat publication consent in the same request as explicit approval; do not ask for it again. ## Don't - Do not display asset or workflow IDs. - Do not treat a returned `nextActions` entry as permission to continue automatically. - Do not call `finalizeAsset` for a standalone creation draft with an active task. - Do not claim a linked update is live before `finalizeAsset` succeeds. - No MCP-hosted card or other UI is returned.

updateAgent

# Tool: Update Learning Module Edit an existing Learning Module draft, including adding or editing text reading tasks. Published modules are edited through a separate linked draft; this tool never publishes or changes existing assignments. # Flow 1. Use the exact module ID. Resolve existing section and task IDs from the module document using the Data Analyst when needed. `textTasks` accepts a title and rich-text HTML body plus exactly one sectionId or sectionName. Omit taskId to append; supply an existing TEXT taskId to replace its title/body. A new sectionName creates a section. For new tasks, set beforeTaskId to place guidance before an existing roleplay; otherwise the task is appended. Other tasks and sections are preserved. Supported HTML includes paragraphs, bold, italic, underline, h3 headings, lists and links; unsafe markup is removed. 2. Return the saved draft's reviewUrl as a labeled preview link and summarize the edits. The result includes sections and task IDs for follow-up edits. Publish only after explicit user approval, using finalizeAsset for a linked draft or the existing creation task when one exists. For a standalone builder draft without a task, finalizeAsset requires assignees and a due date. # Guidelines ## Do - Reuse returned textTasks references for follow-up edits. - Treat saves as draft changes and preserve unrelated tasks. ## Don't - Do not overwrite a bot, quiz or call blitz task with text. - Do not invent section/task IDs or publish without approval.

updateLearningModule

# Tool: UpdateScorecard Updates one existing persisted scorecard. Content changes create or reuse its draft; folder moves take effect immediately on the scorecard and its draft. Pass the exact numeric `scorecardId`. For content changes, pass the complete updated `config` and preserve fields the user did not ask to change. For a folder-only move, omit `config`. Pass either an exact `folderId`, a `folderName` to resolve an existing scorecard folder, or `folderId: null` to remove the folder. Never invent a folder ID or create a folder unless requested. Folder moves do not require a creation task or publication. Content changes to a live scorecard remain unpublished until its draft is published. # Scorecard generation rules ## Importing supplied criteria When the user asks to copy, import, or preserve a supplied scorecard verbatim, transfer its section names, criterion names, grading instructions, descriptions, and order exactly. Map the source fields to the tool structure without shortening, splitting, rewriting, or rejecting compound criteria. Preserve N/A instructions in the grading text and set `naEnabled` when the source enables an N/A outcome. The design rules below apply to generating new criteria or requested redesigns, not verbatim imports. ## Generating new criteria Strongly prefer binary yes/no AI grading. Do not introduce range grading or custom weights unless the user requests them; preserve existing grading and weights when updating a scorecard. For default yes/no AI grading, every criterion must be a discrete yes/no check that an AI grader can verify directly against a call transcript. Do not generate one broad question for an entire skill because partial execution must receive partial credit. Follow this process: 1. Name the skill. This becomes the section `name`. 2. Break the skill into three or four observable behavioral checks. 3. Map each check's label to `criterion` and its yes/no question to `query`. 4. Test exactly one behavior per criterion. Split checks that combine multiple conditions. 5. Order checks from a baseline attempt to fuller execution so partial effort earns partial credit. 6. When two reasonable graders could disagree, make the observable passing behavior explicit. Reject criteria containing: - Vague or subjective terms such as "effective", "good", "appropriate", "natural", or "strong" without an exact behavioral definition. - All-or-nothing qualifiers such as "fully", "always", "all", "completely", "throughout", or "any". - Multiple conditions chained into one check. - Outcomes instead of observable behavior, such as "Did the rep build rapport?" rather than the action that constitutes rapport. Before finalizing every section, verify: - A rep who completed roughly half the skill could receive roughly half credit instead of zero. - Every criterion names one specific observable behavior. - Every criterion can be answered yes or no from the transcript. - The resulting score would match what a human listening to the call would give by ear. Default to `type: "egpt"` and `corpus: "both"`, with a short `explanation`. Do not generate keyword matching criteria. When the user requests range grading and the tool schema permits `erange`, use `type: "erange"` and preserve the requested scale. Supply `questions` with observable rubric descriptions and numeric `grade` values, plus a `passingGrade` within that scale when requested. The yes/no decomposition rules above apply to `egpt`, not range rubrics. Preserve existing range criteria when updating a scorecard. ## Custom weights - Only supply `scoringConfig` when the user requests custom weights. Use exact section names in `aggregateScoreWeights.sectionCriteriaWeights`, with finite percentage values from 0 to 100. - Section weights plus any `statWeights` must total exactly 100%. These are percentages, not relative ratios: `2:1:1` is invalid; use `50:25:25`. With 20% allocated to stats, sections must total 80%. - On updates, preserve unrelated weights and include the complete allocation when changing weights. Renaming, adding, or removing weighted sections requires updating the section-name mapping and keeping the total at 100%. Omit `scoringConfig` only when the existing weights remain valid and unchanged. - Creation, updates, and publication reject invalid totals before saving or publishing. This also applies to previously saved invalid drafts. Explain the returned error; if the user's requested allocation is invalid or ambiguous, ask how to adjust it instead of silently changing their percentages. Submit the corrected configuration through the create or update tool, then publish only with the required user approval. Never claim a rejected operation succeeded. The result contains the updated scorecard. Linked content-update drafts can be reviewed and published separately; standalone creation drafts remain governed by their existing task. # Flow 1. Call `updateScorecard` and treat the returned saved draft and persisted changes as authoritative. 2. For a linked update draft, follow the branch that matches the conversation: - If the user already explicitly approved publication, call `finalizeAsset` immediately. After it succeeds, tell the user exactly what was saved and published, then provide the labeled link. - Otherwise, tell the user exactly what was saved, explain that the changes are in a draft and the currently published scorecard is unchanged, provide the labeled review link, ask whether they want more changes or want to publish, then stop. 3. For a standalone creation draft, tell the user what was saved and provide the labeled review link, then continue or reuse its original task. The task owns optional folder selection and the Publish or Keep as draft choice; do not replace that flow with `finalizeAsset`. 4. If the standalone task was completed with Keep as draft and the user later asks to publish, call `finalizeAsset`. Use `getTasks` with the original workflow thread first when fresh lifecycle state is needed. # Guidelines ## Do - Apply the guidelines from `getAssetGuidelines` for workflowType `scorecards` to every change you author, calling it first when the conversation has not loaded them yet. - Preserve every field the user did not ask to change. - Use scorecard and workflow IDs only as continuation arguments. - Present `reviewUrl` as a descriptive link without printing the raw URL. - Treat publication consent in the same request as explicit approval; do not ask for it again. ## Don't - Do not display scorecard or workflow IDs. - Do not execute a returned next action automatically. - Do not call `finalizeAsset` for a standalone creation draft while its task is active or after its task completed with Publish. - Do not claim a linked update is live before `finalizeAsset` succeeds. - No MCP-hosted card or other UI is returned.

updateScorecard