Perigon

Export signal events using a structured query API. No raw SQL — specify signals, fields, filters, aggregations, and ordering. EVENT and MENTIONS signals only — TOPIC (briefing) signals will error; use signal_insights_list_newsletters / signal_insights_read_newsletter instead. Returns a preview of the first rows plus an S3 file path for the full dataset (JSONL). Available fields: eventType, eventDate, createdAt, updatedAt, summary, uuid, data, articles, signalId, or data.<path> for JSONB subfields (e.g. data.companyName). Filter options: eventTypes (list), date ranges (eventDateFrom/To, createdAtFrom/To), JSONB containment (data: [{op: CONTAINS, value: {key: val}}]). Select expressions: {type: 'field', name}, {type: 'date_trunc', granularity: HOUR|DAY|WEEK|MONTH|QUARTER|YEAR, field}, {type: 'agg', function: COUNT|COUNT_DISTINCT|SUM|AVG|MIN|MAX, field?}. Group by / order by: use {index: N} (1-based) when select is provided, or {field: 'name'} when select is omitted. Omit select to fetch all scalar event fields. Results are written to S3 and accessible in the sandbox at /home/user/workspace/artifacts/<filename>.

signal_insights_export_events

Report this API key's scopes, organization, usage quota, pagination limits, and the entitlement behavior those scopes imply (which article fields always come back null, which filter params will 403, and any silent date-window clamps). Call this once at the start of a session, or whenever a field is unexpectedly null, a 403 occurs, or coverage before/after a date seems to be missing — a null field or empty date range may reflect this key's plan rather than absent data. Calling this tool does not count against the account's request quota.

get_api_access

Retrieve the complete configuration for one Perigon monitor by UUID, including its objective, status, classification, article query, output schema, schedule, watchlist, and delivery contact points. Schedule hours are wall-clock times in timezoneId.

get_monitor

Retrieve structured matches emitted asynchronously by an EVENT or MENTIONS monitor. Returns extracted schema data, event summaries, matched entities, and a bounded set of related article details. Use pagination or date filters for additional results.

get_monitor_events

Retrieve human-readable briefings generated on a monitor's schedule, typically for TOPIC monitors. Returns newsletter content and bounded citation metadata. Use pagination, title, or date filters for additional results.

get_monitor_newsletters

Retrieve rolling AI-generated summaries produced as a monitor processes matching content. Use pagination or creation-date filters to inspect summary history.

get_monitor_summaries

Look up one news source/publisher by its exact ID or domain. Use this after search_sources or search_news_articles surfaces a source you want full detail on — `id` is @InternalParameter on search_sources, so this endpoint is the only route to a single source's paywall status, alt names, and location.

get_source_by_id

Create a new Signal Insights analysis workspace. Call this ONCE at the beginning of any conversation that needs data analysis. Returns a workspace handle required by all analysis tools (signal_insights_execute_code, signal_insights_shell, signal_insights_export_events, file tools). Do NOT invent workspace IDs — always use the one returned here.

signal_insights_create_workspace

Run a bash command in the E2B sandbox environment. Working directory is /home/user/workspace. Query data files are accessible at /home/user/workspace/artifacts. No internet access except *.amazonaws.com.

signal_insights_shell

Search 230k+ journalist and reporter profiles in the Perigon database. Use this to find who covers specific topics, publications, or regions — or who is personally based in a place. Two distinct location concepts: `countries` filters reporting focus (what they cover, derived from their published articles), while `locationCountry`/`locationState`/`locationCounty`/`locationCity`/`locationArea` filter their own profile location (where they are based) — these levels AND together, so pass only the narrowest level the user named. Also filter by name, Twitter handle, publication, content category, topic, or posting activity. Returns journalist profiles with their top sources, profile locations, reporting-focus countries, and monthly posting frequency. A location query returning nothing is usually a casing mismatch (exact-term matching), not an absence of journalists.

search_journalists

List files in a directory of the sandbox workspace. Default directory is the workspace root (/home/user/workspace).

signal_insights_list_files

List newsletters (briefings) for a TOPIC signal. Returns title, short excerpt (~500 chars), and timestamps — not full content. Only works for TOPIC signals; EVENT and MENTIONS will error. Use after signal_insights_read_signal confirms classificationType is TOPIC, then call signal_insights_read_newsletter for full content.

signal_insights_list_newsletters

List and search the authenticated user's Perigon monitors. Use this first to discover monitor UUIDs, inspect statuses, or find monitors by name or classification. Archived monitors are excluded unless explicitly requested.

list_monitors

List or get by UUID the organization's contact points (delivery channels used by monitor notifications — email or webhook). Read-only; use this to find a contactPointId before wiring it into create_monitor/update_monitor.

contact_points

List, get by ID, or resolve by exact name the organization's custom source groups (curated domain bundles usable via the sourceGroup filter, alongside built-ins like top10/top100). Pass id for a single lookup, resolveNames to look up by exact name, or neither to list/search.

source_groups

List, get by ID, or resolve by exact name the organization's watchlists (curated people/company lists used to scope monitors and article searches via the watchlist filter). Pass id for a single lookup, resolveNames to look up by exact name, or neither to list/search by nameContains.

watchlists

Quick shortcut to get recent news for a geographic location (city, state, or country). Automatically detects the location type and applies appropriate geographic filters. Use this for simple 'what's happening in [location]?' queries. For advanced filtering, use search_news_articles with explicit city/state/country parameters instead.

get_location_news

Search 650k+ public figures, politicians, celebrities, executives, and newsworthy individuals in the Perigon database. Use this to look up biographical information about specific people or find people by occupation. Filter by name, occupation, or Wikidata ID. Returns biographical profiles with name, aliases, occupation, position, political party, gender, dates of birth/death, and description. Prefer wikidataId over personName on search_news_articles to avoid name ambiguity.

search_people

Quick shortcut to get recent news about a specific person by name. Automatically looks up the person's profile for context, then finds recent articles mentioning them within a configurable time window. Use this for simple 'what's the latest news about [person]?' queries. For advanced filtering, use search_news_articles with personName instead.

get_person_news

Render a chart to the user. Use this whenever you want to DISPLAY a chart — it is the only tool whose output appears in the interactive chart viewer. Runs Python in the SAME persistent Jupyter kernel as signal_insights_execute_code, so variables, imports, and DataFrames computed there are available here. Do data prep/analysis in signal_insights_execute_code; use this tool only for the plotting code. Call plt.show() after the chart. One plt.show() per chart; for multiple charts call this tool separately. No outbound internet access except *.amazonaws.com.

signal_insights_preview_chart

Read a file from the sandbox workspace. Internally, this reads the full file into memory. Use on files up to a few MB; for larger files, use signal_insights_execute_code directly instead.

signal_insights_read_file

Fetch a full newsletter by UUID and return it as markdown (YAML frontmatter + body). Use after signal_insights_list_newsletters to get complete briefing content for context or analysis. Only works for newsletters belonging to TOPIC signals.

signal_insights_read_newsletter

Get full signal metadata including classificationType and type-specific fields. EVENT/MENTIONS: data schema, event types, event count — use before export_events. TOPIC: newsletterCount and date range — use list_newsletters / read_newsletter.

signal_insights_read_signal

Execute Python code inside a persistent sandboxed Jupyter kernel (IPython). State is fully preserved between calls: variables, imports, DataFrames, fitted models, and function definitions all remain in memory. WORKSPACE (/home/user/workspace): default working directory. Use this to create any files you need. DATA (/home/user/workspace/artifacts): S3-backed read-write directory. Query result files appear here automatically. This directory persists across sandbox restarts. OUTPUT (/home/user/workspace/artifacts/output): write user-facing deliverables here (charts, reports, CSVs, exports). Files in output/ appear in the user's Artifacts panel and are downloadable. Internal/intermediate files should stay in DATA root. Pre-installed highlights: pandas, numpy, matplotlib, seaborn, scipy, scikit-learn, statsmodels, pyarrow, polars, openpyxl, sqlalchemy, beautifulsoup4, nltk, xgboost, lightgbm, shap, pillow, sympy, tabulate, rich. CHARTS: charts produced here (e.g. via plt.show()) are NOT displayed to the user. To show a chart to the user, call signal_insights_preview_chart with the plotting code instead. Before groupby/value_counts/top-N charts, drop rows with missing category values (dropna / notna on the label column) — null categories often dominate and mislead. No outbound internet access except *.amazonaws.com.

signal_insights_execute_code

Search a file's contents for lines matching a regex pattern. Reads the file via the SDK (no shell injection risk). Returns matching lines with line numbers. Use on files up to a few MB; for larger files, use signal_insights_execute_code directly instead.

signal_insights_grep

Generate an AI-powered summary of news coverage matching your filters. Use this when the user wants a synthesized overview or briefing on a topic rather than a list of individual articles. Combines article search with LLM summarization to produce concise, coherent summaries with supporting article citations. Accepts all standard article filters (keywords, categories, topics, sources, dates, locations) plus summarization controls (prompt, model, temperature).

summarize_news

Search for signals by name or monitoring objective. Optional classificationTypes filter: EVENT, MENTIONS, TOPIC (briefings). Omit for all types. Results include classificationType, eventCount, and newsletterCount. Use this to find relevant signals before fetching data. If the search query is not present, this can be used to list all available signals.

signal_insights_search_signals

Activate, pause, or archive a Perigon monitor. ACTIVE starts its processing pipeline, STOPPED pauses it, and ARCHIVED hides it from default lists and cannot be reversed through the public API. Use only when the user explicitly requests the lifecycle change.

set_monitor_status

Search 200k+ news publications and media outlets in the Perigon database. Use this to discover or compare news sources by name, domain, location, audience size, or publishing volume. Filter by curated bundles (top10, top100), paywall status, or geographic location. Returns source profiles with domain, monthly visits, top topics covered, and publishing frequency.

search_sources

Search clustered news stories (headlines) that group related articles across multiple sources into a single narrative. Use this to understand major news events, trending headlines, and story arcs rather than finding individual articles. Filter by category, topic, source, location, person, company, or time range. Returns summaries, key points, unique/total article counts, sentiment, and top topics/categories/people/companies/locations for the cluster. Feed the id into search_story_history to see how the story evolved, or search_news_articles(newsStoryIds) to pull its member articles.

search_news_stories

Search story history to track how news stories evolve over time. Returns timestamped snapshots of story clusters including summaries, short summaries, key points, and changelogs. Use this to understand how a story has developed, what changed between updates, and to review the timeline of a news event. Filter by cluster ID, date range, sort order, or changelog presence. Only use this tool instead of search_news_stories tool when you need to understand the history of a story.

search_story_history

Get story-level (clustered headline) volume or velocity over time — the story equivalent of get_article_counts. Use metric='volume' for publication counts bucketed by time, or metric='velocity' for how fast specific clusters are accumulating mentions (requires clusterId from search_news_stories). Requires the CLUSTERS permission.

get_story_stats

Get the companies whose news coverage is spiking — mentioned significantly more in a recent window than a prior baseline period. Use this when the user asks 'which companies are trending?', 'which companies are getting more coverage than usual?', or 'what companies are suddenly in the news?' — NOT for simple most-mentioned frequency (use get_top_entities for that). Returns a ranked list with current mention count, baseline count, and a spike score (higher = bigger relative increase). The comparison window defaults to last 3 days vs. last 30 days; override with currentFrom/To and baselineFrom/To. Supports all standard article filters to scope the analysis to a specific topic, source, or date range.

get_top_companies

Get the most frequently mentioned entities in articles matching the given filters, ranked by raw mention count. Use this when the user asks 'what topics/people/companies are most covered?' or 'who appears most in X news?' — i.e., questions about overall mention frequency within a fixed window. Do NOT use this for detecting sudden spikes or trending entities; use get_top_people or get_top_companies for spike detection instead. Defaults to returning topics, people, and companies; use the entity parameter to request other types (cities, journalists, sources). Supports the same article filters as search_news_articles.

get_top_entities

Get the people whose news coverage is spiking — mentioned significantly more in a recent window than a prior baseline period. Use this when the user asks 'who is trending?', 'who suddenly got a lot of coverage?', or 'which people are in the news more than usual?' — NOT for simple most-mentioned frequency (use get_top_entities for that). Returns a ranked list with current mention count, baseline count, and a spike score (higher = bigger relative increase). The comparison window defaults to last 3 days vs. last 30 days; override with currentFrom/To and baselineFrom/To. Supports all standard article filters to scope the analysis to a specific topic, source, or date range.

get_top_people

Get the topics whose news coverage is spiking — mentioned significantly more in a recent window than a prior baseline period. Use this alongside get_top_people and get_top_companies when the user asks 'what topics are trending?' The comparison window defaults to last 3 days vs. last 30 days; override with currentFrom/To and baselineFrom/To. Supports the same curated article filters as the other stats tools.

get_top_topics

Browse and search the Perigon topic taxonomy. Use this to discover available topics for use as filters in other search tools (articles, stories, journalists). Topics are more granular than categories. Filter by name, category, or subcategory. Returns topic names with their category/subcategory classification.

search_topics

Partially update a Perigon monitor's configuration. Omitted fields remain unchanged; query, schema, schedules, entity groups, and contact points are complete replacements when provided. Use set_monitor_status for lifecycle changes.

update_monitor

Partially update a source group. Only provided fields are changed; the domains array is replaced wholesale when provided, not merged. Only use this when the user explicitly asks to modify a source group.

update_source_group

Partially update a watchlist. Only provided fields are changed; people/companies arrays are replaced wholesale when provided, not merged. Only use this when the user explicitly asks to modify a watchlist.

update_watchlist