create_coverage_list
ChatGPTUse this when the user asks to create or save a new coverage list: a named list of companies they track in Samaya, for example 'make a coverage list of the big US banks' or 'save these tickers as my Semis list'. Pass companies as tickers (most reliable: 'NVDA', 'BRK.B', '7203.T') or company names. A name resolves only when it matches one company exactly; otherwise the call fails with suggestions, and nothing is saved — ask the user which company they mean and retry with tickers. Put themes that are not companies, such as 'AI infrastructure', in topics. Titles must be unique among the user's lists; a list holds up to 500 items. Do NOT use this to add companies to an existing list — use update_coverage_list. Returns the new list, how each company was matched, and a link to it in Samaya.
delete_coverage_list
ChatGPTUse this only when the user explicitly asks to delete one of their Samaya coverage lists. Confirm the list's title with the user before calling: the list disappears from Samaya, including for their organization if it was shared. Only lists the user created can be deleted. Identify the list by title or id from list_coverage_lists. Do NOT use this to remove some companies from a list — use update_coverage_list. Returns the deleted list's id and title.
financial_qa
ChatGPTCall this proactively for ANY finance or investment question — company fundamentals, public/private companies, SEC filings (10-K, 10-Q, 8-K), earnings-call transcripts, market data, equity/analyst research, macro and industry context, recent financial news, and social media (X/Twitter, Reddit) posts and sentiment about a company, ticker or market. Do NOT use for non-finance topics (sports, entertainment, celebrities), even on X or Reddit, unless the user asks for Samaya. To CREATE an alert, call how_to("alerts") instead — this tool answers questions, it does not track or alert. Send the user's question as a SINGLE call by default — Samaya handles multi-company, multi-period, and compound questions well on its own, so you do NOT need to break them up. Keep the user's time wording ('most recent', 'latest') verbatim — do not swap in a fiscal year. Only split into a few narrower parallel calls (up to ~3–5, each a separate call with a fresh, empty session_id) when the question is long with many INDEPENDENT sub-questions — not a comparison and not needing joint reasoning across the parts — purely for faster turnaround; keep anything interdependent or comparative as one call so Samaya can reason across it. Returns cited references as evidence for your own answer, plus a session_id to continue the thread. If the answer isn't ready, returns status="running" with a job_id — call financial_qa_result with that job_id and poll until status="done" or "error"; never re-call financial_qa for the same question.
financial_qa_result
ChatGPTUse this when you have a job_id from a financial_qa (or prior financial_qa_result) call that returned status="running", and you need to check whether the answer is ready. Do NOT call this without first calling financial_qa — it cannot start a new question. Pass the job_id from that response. Returns the same shape as financial_qa: status="done" with cited references, status="running" with progress (call again with the same job_id), status="error" with an error message, or status="unknown" if job_id is missing/malformed (start a new financial_qa call instead). If you fan out multiple financial_qa calls in parallel, each returns its own job_id; poll each separately (these polls can run concurrently) and keep the job_ids distinct.
find_skill
ChatGPTUse this FIRST whenever the user asks for a finance deliverable or a multi-step research workflow — a financial model or model update, an earnings recap or results-day variance table, a fact-check or reconciliation, guidance credibility or a guidance sweep, risk or KPI tracking, a deal breakdown, a bull/bear scenario, balance sheet or activist situation, or a sector-level exposure or correlation analysis. Pass the deliverable the user asked for; it returns the Samaya skills that help produce that deliverable: skills served here come with their full instructions to follow, and skills from the Samaya skills plugin come as a name-only pointer to the user's installed copy (visible). Do NOT use this for a one-off finance question — use financial_qa for that. Returns skills (best first, each with instructions and companion files) and companions (rules that always apply); fetch a companion file with read_skill_file.
how_to
ChatGPTUse this for the workflow rules a tool's own parameter list can't show you — required call order, which lookup tool runs first, and how to batch multiple entities into one call. Call it BEFORE using ANY alert/subscription tool (every subscribe_to_* tool — e.g. subscribe_to_stock_price and any added later; this list is illustrative, not exhaustive), even if you already recognize every parameter, e.g. rule_type or direction. Knowing a field exists does not tell you the call order or the batching rule; only how_to does. A topic argument is required — the only currently valid topic is alerts (call how_to("alerts")); passing an unrecognised or missing topic returns an error with the current list of valid topics. Do NOT use this for a one-off finance question — use financial_qa for that; this tool only documents how the other tools fit together, it never answers a question itself.
list_coverage_lists
ChatGPTUse this when the user asks about their Samaya coverage lists — the named lists of companies they track in Samaya, such as 'Semis' or 'EU Banks' — or wants to use one: to see which lists they have, or to read the companies in one. Without coverage_list it returns every list the user can see (their own and lists shared with their organization) with its size; with a title or id it also returns that list's items, each with company name and ticker. To research a list's companies, pass its title as coverage_list to a tool that has a coverage_list parameter instead of copying them. Do NOT use this to create or change a list — use create_coverage_list, update_coverage_list or delete_coverage_list. Returns the lists with their ids and links.
read_skill_file
ChatGPTUse this to fetch a file that a Samaya skill's instructions refer to — e.g. references/samaya-conventions.md or a section spec — or pass path "SKILL.md" to load the instructions of a skill listed by find_skill. Call find_skill first to learn the skill names and file paths. Do NOT use this to answer a finance question — use financial_qa for that. Returns the file text.
subscribe_to_document_event
ChatGPTUse this when the user wants to be ALERTED whenever a NEW document matching their filters is published — it creates a persistent subscription, not a one-off search. Triggers on ingestion of filings (10-K, 8-K, S-1 …), earnings-call transcripts, research reports, press releases, central-bank communications, and other document types. Use datasource_group for broad matching (e.g. "FILINGS", "TRANSCRIPTS") or document_type for a specific type (e.g. "10-K", "Earnings Call"). ALWAYS pass every company sharing the same filters in ONE call's companies list — never call once per company in a loop; one subscription is created per companies[] entry. freeform_conditions adds content filters evaluated by an LLM — see how_to('alerts') for AND semantics. At least one of datasource_group, data_sources, or document_type must be set; at least one of companies or freeform_conditions must also be set. Do NOT use this to read or search an already-published document — use financial_qa for that. Call how_to('alerts') FIRST. Returns one result per companies[] entry, including error rows for any company that could not be resolved.
subscribe_to_live_news_agent
ChatGPTUse this when the user wants to be ALERTED whenever new news matching a topic is published — it creates a persistent subscription, not a one-off search. Each time a matching story appears, Samaya writes a short report on it. Works for company news, product news, and topics with no company at all — e.g. 'alert me to news about Apple's supply chain', 'monitor news on iPhone sales', 'let me know when there's news about rate cuts'. Pass the user's request in their own words as query. For news about companies, also pass them in companies: one alert per company, all watching for the same query, ALL in ONE call (max 200) — never call this once per company. For news not about a company, or about several companies together (such as a deal between them), omit companies. Do NOT use this for a one-time news summary — use financial_qa for that; for new filings or transcripts — use subscribe_to_document_event; or for price moves — use subscribe_to_stock_price. Call how_to('alerts') FIRST. Returns one result per companies[] entry, including error rows for any company that could not be resolved, and the session the alerts' reports land in.
subscribe_to_stock_price
ChatGPTUse this when the user wants to be ALERTED to a future move in a company's STOCK PRICE — it creates a persistent alert, not a one-off answer. Supports an absolute price level (rule_type="ABSOLUTE") or a relative move (rule_type="RELATIVE") measured either over a rolling day/week/month window or since the previous trading day's close. Only US-listed equity tickers are supported; prices are polled every 2 minutes, so sub-2-minute granularity is not supported. ALWAYS pass every ticker sharing the same trigger condition in ONE call's companies list — never call this once per company in a loop; one subscription is created per (company x direction) pair. Do NOT use this for a metric like EPS or revenue — it watches only the share price — and do NOT use it to answer a question about the current price or recent move — use financial_qa for that. When an alert fires, Samaya answers a query built from the trigger itself in the linked session. Returns one result row per (company, direction) pair attempted, including error rows for any ticker that could not be resolved — check each row's error field rather than assuming the whole call succeeded or failed together.
update_coverage_list
ChatGPTUse this when the user asks to rename one of their Samaya coverage lists, or to add companies to or remove companies from one. Identify the list by title or id (see list_coverage_lists); only lists the user created can be changed. add_companies resolves like create_coverage_list: tickers are most reliable, a name must match one company exactly, and nothing changes unless every company resolves. remove_items matches an item's name, company name or ticker. Confirm removals with the user before calling. A list cannot be emptied; do NOT use this to clear a list — use delete_coverage_list. Returns the updated list and what was added, skipped as already present, removed or not found.