Searcher OS
Manage the user's M&A deal pipeline, search for businesses on the market, track broker relationships, review inbound emails, run SBA loan calculations, manage deal tasks, and analyze CIM documents via the Searcher OS REST API.
Setup
Authentication is handled by the Searcher OS plugin. If you haven't signed in yet, run /searcheros-login. The user must have a Searcher OS account on the Searcher ($90/mo) or Deal Team ($244/mo) plan.
API
Base URL: INLINECODE1
All tool calls use a single endpoint:
CODEBLOCK0
Responses:
- - Success: INLINECODE2
- Error: INLINECODE3
- Confirmation needed: INLINECODE4
Tool Discovery
Call GET https://searcheros.ai/api/agent/tools with the same Authorization header to get the live list of all available tools with their descriptions and parameter schemas. Use this to stay current as new tools are added.
Session Start
At the start of every conversation, call get_context first. It returns the user's name, buy boxes, pipeline stage counts, and feed stats in a single call. Use this to:
- 1. Greet the user by name
- Give a brief pipeline status (e.g., "You have 12 active deals: 5 Interested, 3 NDA Signed, 2 CIM Review, 2 Conversations")
- Highlight anything notable (e.g., "47 new deals came in this week")
- Suggest 2-3 next actions:
- "Want me to check your newest on-market deals?"
- "Ready to update the stage on any deals?"
- "Want to search for deals matching your buy box?"
Available Tools
Context
- - getcontext — Get session context: user profile, buy boxes, pipeline counts, feed stats. Call FIRST at start of every conversation.
- ping — Health check. No params.
- buybox_list — Get user's acquisition criteria (buy boxes). No params.
Pipeline (My Deals)
- - pipelinelist — List tracked deals. Params:
stage? (interested|ndasigned|cimreview|conversations|loisent|duediligence|closed|dead), search? (string), limit? (default 20, max 100), INLINECODE10 - pipelinegetdeal — Get full deal details. Params:
opportunity_id (uuid, required) - pipelinestagecounts — Count deals per stage. No params.
- pipelinemovestage — Move deal to new stage. Needs confirmation. Params:
opportunity_id (uuid), new_stage (enum) - pipelineaddnote — Add note to deal. Params:
opportunity_id (uuid), notes (string) - pipelinekilldeal — Kill a deal. Needs confirmation. Params:
opportunity_id (uuid), kill_reason (financialdiscrepancy|dealsizeinsufficient|concentrationrisk|industrymismatch|nobrokerresponse|overpriced|intuitiverejection|competition|location|other), INLINECODE18 - pipelineupdatedeal — Update deal metadata (star, label, next action, priority). No confirmation needed. Params:
opportunity_id (uuid), is_starred? (boolean), deal_label? (green|yellow|red|null), next_action? (string|null, max 500), next_action_due? (ISO date string|null), priority? (0-10) - pipelineloginteraction — Log an interaction (call, email, meeting, note) directly on a deal without needing a broker. No confirmation needed. Params:
opportunity_id (uuid), interaction_type (call|emailsent|email_received|meeting|note), subject? (max 300), notes? (max 5000), broker_id? (uuid, optional)
Feed (On-Market Deals)
- - feedsearch — Search on-market deals. Params:
keyword?, industry? (slug), states? (string[]), msas? (string[], metro areas), min_price?, max_price?, min_ebitda?, max_ebitda?, min_revenue?, max_revenue?, min_margin?, max_margin? (0-1), min_multiple?, max_multiple?, buy_box_id?, freshness_hours?, sort_by? (firstseen|askingprice|sdeebitda|grossrevenue), sort_order? (asc|desc), limit? (default 20, max 50), INLINECODE49 - feedcount — Count matching deals. Params:
keyword?, industry_filter?, states? (string[]), buy_box_id?, freshness_hours?, price_dropped? (boolean), min_price?, max_price?, min_ebitda?, max_ebitda?, min_revenue?, INLINECODE61 - feedstats — Feed statistics (price distribution, industry/source breakdown). No params.
- feedsavedeal — Save deal to pipeline. Needs confirmation. Params:
staging_listing_id (uuid), INLINECODE63 - feeddismiss_deal — Dismiss deal from feed. Auto-approved by default. Params:
staging_listing_id (uuid)
Inbox (Inbound Emails)
- - inboxlist — List emails. Params:
status? (unmatched|matched|ignored), limit?, INLINECODE67 - inboxgetemail — Get full email. Params:
email_id (uuid) - inboxlinktodeal — Link email to deal. Needs confirmation. Params:
email_id (uuid), opportunity_id (uuid) - inbox_ignore — Ignore email. Params:
email_id (uuid)
Brokers
- - brokerlist — List brokers. Params:
search?, sort_by? (name|company|dealcount) - brokerget — Get broker details. Params:
broker_id (uuid) - brokercreate — Add broker. Needs confirmation. Params:
name (required), email?, phone?, INLINECODE78 - brokerloginteraction — Log interaction. Needs confirmation. Params:
broker_id (uuid), interaction_type (call|emailsent|emailreceived|meeting|note), subject?, notes?, INLINECODE83
CIM (Confidential Information Memorandums)
- - cimlist — List CIM analyses for a deal. Params:
opportunity_id (uuid) - cimgetanalysis — Get CIM analysis details. Params:
cim_id (uuid) - cimsearch — Search across CIM analyses. Params: INLINECODE86
Calculator
- - calculator_run — Run an SBA 7(a) loan calculation. Computes DSCR, monthly payments, cash flow, and deal structure. Returns a verdict (FAIL/RISKY/PASS/GOOD/STRONG). Params:
asking_price (required), sde (required), down_payment_pct? (default 0.10), sba_rate? (default 0.105), sba_term_years? (default 10), seller_note_pct? (default 0), seller_note_rate? (default 0.06), seller_note_term_years? (default 5), buyer_compensation? (default 0), working_capital? (default 0), include_working_capital_in_loan? (default true)
Tasks
- - tasklist — List tasks for deals. Returns incomplete tasks by default. Params:
opportunity_id? (uuid, filter to single deal), stage? (pipeline stage filter), include_completed? (default false), limit? (default 50, max 100), INLINECODE102 - taskupdate — Update a task. Mark complete/incomplete, change priority, set due date, or rename (manual tasks only). Completing the last task in a stage may auto-advance the deal. No confirmation needed. Params:
task_id (uuid, required), completed? (boolean), title? (manual tasks only, max 500), priority? (1=High, 2=Medium, 3=Normal, manual tasks only), due_date? (YYYY-MM-DD|null)
Confirmations
Write operations may return
"status": "pending_confirmation". Use these tools to manage:
- - confirmationlistpending — List pending confirmations. No params.
- confirmationcheckstatus — Check status. Params:
confirmation_id (uuid) - confirmationresolve — Approve or deny. Params:
confirmation_id (uuid), decision (approved|denied) - confirmationgetautoapprove — Get auto-approve settings. No params.
Confirmation Flow
Some tools (marked "Needs confirmation") require user approval before executing:
- 1. Call the write tool (e.g.,
pipeline_move_stage) - If result has
"status": "pending_confirmation" — tell the user it needs their approval - The user can approve in the Searcher OS web app OR tell you "yes, approve it"
- If user says approve: call
confirmation_resolve with INLINECODE115 - The action executes and returns the result
- Confirmations expire after 30 minutes if not resolved
Rate Limits
100 requests per minute per API key. On 429 responses, check the Retry-After header.
Searcher OS
管理用户的并购交易管道，搜索市场上的企业，跟踪经纪人关系，审查收到的电子邮件，运行SBA贷款计算，管理交易任务，并通过Searcher OS REST API分析CIM文档。
设置
认证由Searcher OS插件处理。如果您尚未登录，请运行/searcheros-login。用户必须拥有Searcher（每月90美元）或Deal Team（每月244美元）套餐的Searcher OS账户。
API
基础URL： https://searcheros.ai/api/agent
所有工具调用使用单一端点：
POST https://searcheros.ai/api/agent/invoke
Authorization: Bearer $SEARCHEROSAPI_KEY
Content-Type: application/json
{tool: , params: {}}
响应：
- - 成功：{ok: true, result: {...}}
- 错误：{ok: false, error: {code: ..., message: ...}}
- 需要确认：{ok: true, result: {status: pending_confirmation, confirmationId: ..., message: ..., expiresAt: ...}}
工具发现
调用GET https://searcheros.ai/api/agent/tools，使用相同的Authorization头，获取所有可用工具的实时列表及其描述和参数模式。随着新工具的添加，使用此方法保持最新。
会话开始
在每次对话开始时，首先调用get_context。它会在一次调用中返回用户的姓名、购买标准、管道阶段计数和动态统计信息。使用此信息：
- 1. 用姓名问候用户
- 提供简要的管道状态（例如：您有12个活跃交易：5个感兴趣，3个已签署NDA，2个CIM审查，2个对话中）
- 突出显示任何值得注意的事项（例如：本周新增47个交易）
- 建议2-3个下一步操作：
- 想让我查看您最新的市场交易吗？
- 准备好更新任何交易的阶段了吗？
- 想搜索符合您购买标准的交易吗？
可用工具
上下文
- - getcontext — 获取会话上下文：用户资料、购买标准、管道计数、动态统计信息。每次对话开始时首先调用。
- ping — 健康检查。无参数。
- buybox_list — 获取用户的收购标准（购买标准）。无参数。
管道（我的交易）
- - pipelinelist — 列出跟踪的交易。参数：stage?（interested|ndasigned|cimreview|conversations|loisent|duediligence|closed|dead），search?（字符串），limit?（默认20，最大100），offset?
- pipelinegetdeal — 获取完整交易详情。参数：opportunityid（uuid，必填）
- pipelinestagecounts — 按阶段统计交易数量。无参数。
- pipelinemovestage — 将交易移至新阶段。需要确认。参数：opportunityid（uuid），newstage（枚举）
- pipelineaddnote — 为交易添加备注。参数：opportunityid（uuid），notes（字符串）
- pipelinekilldeal — 终止交易。需要确认。参数：opportunityid（uuid），killreason（financialdiscrepancy|dealsizeinsufficient|concentrationrisk|industrymismatch|nobrokerresponse|overpriced|intuitiverejection|competition|location|other），killnotes?
- pipelineupdatedeal — 更新交易元数据（星标、标签、下一步操作、优先级）。无需确认。参数：opportunityid（uuid），isstarred?（布尔值），deallabel?（green|yellow|red|null），nextaction?（字符串|null，最大500），nextactiondue?（ISO日期字符串|null），priority?（0-10）
- pipelineloginteraction — 直接在交易上记录互动（电话、电子邮件、会议、备注），无需经纪人。无需确认。参数：opportunityid（uuid），interactiontype（call|emailsent|emailreceived|meeting|note），subject?（最大300），notes?（最大5000），broker_id?（uuid，可选）
动态（市场交易）
- - feedsearch — 搜索市场交易。参数：keyword?，industry?（slug），states?（字符串数组），msas?（字符串数组，都市区），minprice?，maxprice?，minebitda?，maxebitda?，minrevenue?，maxrevenue?，minmargin?，maxmargin?（0-1），minmultiple?，maxmultiple?，buyboxid?，freshnesshours?，sortby?（firstseen|askingprice|sdeebitda|grossrevenue），sortorder?（asc|desc），limit?（默认20，最大50），offset?
- feedcount — 统计匹配的交易数量。参数：keyword?，industryfilter?，states?（字符串数组），buyboxid?，freshnesshours?，pricedropped?（布尔值），minprice?，maxprice?，minebitda?，maxebitda?，minrevenue?，maxrevenue?
- feedstats — 动态统计信息（价格分布、行业/来源细分）。无参数。
- feedsavedeal — 将交易保存到管道。需要确认。参数：staginglistingid（uuid），privatenotes?
- feeddismissdeal — 从动态中忽略交易。默认自动批准。参数：staginglistingid（uuid）
收件箱（收到的电子邮件）
- - inboxlist — 列出电子邮件。参数：status?（unmatched|matched|ignored），limit?，offset?
- inboxgetemail — 获取完整电子邮件。参数：emailid（uuid）
- inboxlinktodeal — 将电子邮件链接到交易。需要确认。参数：emailid（uuid），opportunityid（uuid）
- inboxignore — 忽略电子邮件。参数：email_id（uuid）
经纪人
- - brokerlist — 列出经纪人。参数：search?，sortby?（name|company|dealcount）
- brokerget — 获取经纪人详情。参数：brokerid（uuid）
- brokercreate — 添加经纪人。需要确认。参数：name（必填），email?，phone?，company?
- brokerloginteraction — 记录互动。需要确认。参数：brokerid（uuid），interactiontype（call|emailsent|emailreceived|meeting|note），subject?，notes?，opportunity_id?
CIM（保密信息备忘录）
- - cimlist — 列出交易相关的CIM分析。参数：opportunityid（uuid）
- cimgetanalysis — 获取CIM分析详情。参数：cimid（uuid）
- cimsearch — 跨CIM分析搜索。参数：query?
计算器
- - calculatorrun — 运行SBA 7(a)贷款计算。计算DSCR、月付款、现金流和交易结构。返回判定结果（FAIL/RISKY/PASS/GOOD/STRONG）。参数：askingprice（必填），sde（必填），downpaymentpct?（默认0.10），sbarate?（默认0.105），sbatermyears?（默认10），sellernotepct?（默认0），sellernoterate?（默认0.06），sellernotetermyears?（默认5），buyercompensation?（默认0），workingcapital?（默认0），includeworkingcapitalinloan?（默认true）
任务
- - tasklist — 列出交易的任务。默认返回未完成的任务。参数：opportunityid?（uuid，筛选至单个交易），stage?（管道阶段筛选），include_completed?（默认false），limit?（默认50，最大100），offset?
