# Aunoo Agentic

> The news and foresight harness for agentic AI. Live news coverage with provenance and trust signals, forecasts on where stories are heading, and newsletters on demand, served to AI agents over MCP. Free to start.

Aunoo Agentic is an MCP server. It gives an AI agent grounded, cited answers from current news coverage: who is behind a story (source reliability, ownership, state affiliation, coordinated amplification), where consensus and outliers sit, and where a topic is heading. Other APIs hand your agent articles; Aunoo hands it judgment.

## Connect

- MCP endpoint (Streamable HTTP, POST only): `https://saas.aunoo.ai/mcp`
- Auth: OAuth 2.1 with dynamic client registration and PKCE (S256). Metadata: `https://saas.aunoo.ai/.well-known/oauth-authorization-server` and `https://saas.aunoo.ai/.well-known/oauth-protected-resource`. An unauthenticated request gets a 401 whose WWW-Authenticate header points at that metadata.
- Claude Code: `claude mcp add aunoo https://saas.aunoo.ai/mcp --transport http` then `/mcp` → Authenticate.
- Claude Desktop / claude.ai: Settings → Connectors → Add custom connector, paste the MCP URL, sign in.
- Static key alternative: mint a workspace key in the console (https://saas.aunoo.ai/agentic/console) and send `Authorization: Bearer aunoo_…`.
- REST mirror of every tool: `POST https://saas.aunoo.ai/api/v1/skills/workspace/run` with `{"tool": name, "arguments": {...}}` and the same bearer.
- Server card (SEP-2127): `https://saas.aunoo.ai/mcp/server-card`; catalog: `https://saas.aunoo.ai/.well-known/ai-catalog.json`.

## Sign up and pay as an agent

1. Read the offer: `GET https://saas.aunoo.ai/api/v1/agentic/offer` (public; prices, limits, scopes).
2. Register a client: `POST https://saas.aunoo.ai/oauth/register` with `{"client_name": "my-agent", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"]}`.
3. Start the device flow: `POST https://saas.aunoo.ai/oauth/device_authorization` (form fields `client_id`, optional `scope`). Show the returned `verification_uri_complete` to your human; they sign in with Google or GitHub once and approve. A free workspace is created on that page.
4. Poll `POST https://saas.aunoo.ai/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` until it returns tokens (`authorization_pending` and `slow_down` in between).
5. Call `/mcp` with the access token. Default scope is `mcp:workspace account:topics`; request `account:billing` too if the agent should be able to buy add-ons.
6. Buy an add-on: `POST https://saas.aunoo.ai/api/v1/billing/addons` `{"kind": "skills_addon_foresight", "quantity": 1}` returns a `checkout_url` for your human and a `poll_url`; poll it every 5 s until `fulfilled` is true.

## Tools

Topic-scoped arguments are auto-filled from the topics the workspace subscribes to. Call `list_capabilities` first to learn the topic ids.

- `analyze_sentiment_trends` — Sentiment trends: Aggregate sentiment trends over time
- `fetch_related_to_article` — Related articles: Return articles semantically similar to a given article id via pgvector KNN.
- `follow_up_query` — Follow-up search: Combine previous context with new query results
- `forecast_sentiment_inflection` — Sentiment inflection forecast: Forecast whether a topic's sentiment is about to turn — momentum, the most recent change-point (date + direction + size), and an inflection-risk flag with a projected sign-flip…
- `forecast_topic_trajectory` — Topic trajectory forecast: Forecast a topic's lifecycle phase from its daily article-volume curve — emerging / accelerating / cresting / declining / dormant — with growth rate and, when a curve fits, a pr…
- `get_article_categories` — Article categories: Get category distribution for a topic
- `get_article_full` — Full article: Fetch a single article by id with full content (no 2000-char truncation).
- `get_consensus` — Consensus and outliers: Return Aunoo's cached cross-source consensus analysis for a topic — 3-5 categories where coverage converges, with key insights and source breakdown.
- `get_entity_wiki` — Entity wiki: Fetch the LLM-maintained wiki summary for a named entity within a topic — who they are, when they appeared, key events involving them.
- `get_foresight_component` — Foresight component: Get Aunoo's ACTUAL in-app chart for a topic as a self-contained HTML document (same server-rendered SVG as the app + public share page: the S-curve with scenarios plotted on it,…
- `get_horizons` — Future horizons: Return Aunoo's cached Three-Horizons foresight scenarios for a topic — current developments (H1), emerging shifts (H2), longer-horizon possibilities (H3).
- `get_newsletter_job` — Newsletter job status: Poll the status of a queued newsletter job.
- `get_polarization_index` — Polarization index: Measure how far apart the left and right are framing a topic — a 0–100 score for how separable left- vs right-leaning coverage is in embedding space, plus a trend (widening / na…
- `get_story_coverage` — Story coverage report: Coverage read for a news article: who else is running the SAME story, and Aunoo's verdict on how it's moving — reach (niche / regional / wide / viral), coordination (none / susp…
- `get_topic_articles` — Topic articles: Fetch articles for a specific topic with optional sampling
- `get_trust_signals` — Trust signals for an article: The five per-article Trust Signals Aunoo shows in the app — ① Source (outlet bias / factual record / credibility) ② Claims (per-claim verdicts when the article has been validate…
- `get_trust_signals_for_urls` — Trust signals for URLs: The same five Trust Signals as get_trust_signals, for articles named by URL rather than by Aunoo article id — up to 25 urls.
- `get_validation_job` — Validation job status: Poll the status of a queued validation job.
- `get_world_state` — World state: Returns the platform's maintained record of current entities, topic state, and recent events.
- `list_capabilities` — List capabilities: Return a chat-friendly summary of what this Aunoo connection can do — packs in scope, tool catalogue, named recipes, and a 'how to get started' hint.
- `list_newsletter_jobs` — List newsletter jobs: List the calling tenant's most recent newsletter jobs (default 10, max 50).
- `render_horizons_chart` — Render horizons chart: Render the Three-Horizons foresight as a PNG chart — the same S-curve visual as the in-app Future Horizons page (current H1 declining, transition H2 cresting, future H3 rising)…
- `search_articles_by_keywords` — Keyword search: Keyword search across title, content, and summary
- `search_news` — Search news: Search for news articles (semantic + keyword fallback)
- `semantic_search_and_analyze` — Semantic search and analysis: Vector search for semantically similar articles
- `start_newsletter_job` — Start newsletter job (starts a job): Run Aunoo's server-side newsletter generator.
- `start_validation_job` — Start validation job (starts a job): Queue an independent article fact-check as a background job and return a job_id immediately.
- `validate_article` — Validate article claims (starts a job): Run an independent fact-check on a news article: extracts claims, verifies each against source reputation, corroboration across outlets, external fact-check archives, and synthe…

## Playbooks (MCP prompts)

Multi-step playbooks returned by `prompts/get`; the agent then follows them with the tools above.

- `deep_dive`: Research-style multi-angle dive on a question.
- `consensus_analysis`: Identify 3-4 consensus categories where coverage converges + where it diverges.
- `future_horizons`: Standardized, VISUAL Three-Horizons foresight for a topic: pulls get_horizons + the canonical S-curve, then renders Aunoo's future-horizons component as an artifact (HTML/text f…
- `consensus_outliers`: Standardized, VISUAL Consensus & Outliers for a topic: pulls get_consensus, then renders Aunoo's consensus component (sentiment mix + agreement + minority outliers) as an artifa…
- `foresight_report`: Build ONE cohesive, on-brand report artifact for a topic — orchestrates the full foresight set: the Three-Horizons chart (Aunoo SVG) + scenarios, the computed volume / sentiment…
- `newsletter`: Multi-step playbook for drafting a topic-scoped newsletter in Aunoo's house voice.
- `correspondent_brief`: Short-form briefing (200-300 words) in the voice of a named Aunoo correspondent persona.
- `forecast_brief`: Forward-looking outlook for a topic built from Aunoo's three COMPUTED forecast signals: volume trajectory (lifecycle phase + projected peak), sentiment inflection (is the mood t…
- `investigation`: Rigorous, evidence-first investigation + fact-check of a claim, article, or URL.
- `story_reach`: Trace how a story spread on the covered social platforms and how it was received, and present it as a structured reach card (Spread → Top amplifiers → Reception).

## Pricing

- Free (Reader): $0. 1 subscribed topic(s) and the core toolset above.
- Free-tier cap: 100 tool calls per month. The Agent plan removes the cap; feature add-ons do not.
- Agent plan (`agent`): $19/month. 2000 tool calls included, then 0.01 USD per call; 3 topics; no monthly cap. Buy with POST /api/v1/billing/plans/change {"plan": "agent"}.
- Additional Topic (`topic`): $3/month. One more subscribed topic per unit (raises max_topics by 1).
- Foresight Tools (Consensus + Horizons) (`skills_addon_foresight`): $19/month. The foresight tools: get_consensus, get_horizons, render_horizons_chart, get_foresight_component, forecast_topic_trajectory, forecast_sentiment_inflection, get_polarization_index.
- Newsletter Generator (`skills_addon_newsletter`): $15/month. The newsletter tools: start_newsletter_job, get_newsletter_job, list_newsletter_jobs.
- Add-ons are billed monthly and prorated; cancel from the console.

## Links

- Full tool reference with parameters: https://saas.aunoo.ai/llms-full.txt
- Human-readable docs: https://saas.aunoo.ai/api/v1/skills-docs/docs
- OpenAPI (REST mirror): https://saas.aunoo.ai/openapi.json
- ChatGPT Actions manifest: https://saas.aunoo.ai/api/v1/skills/workspace/openapi.yaml
- Public RSS of open topics: https://saas.aunoo.ai/api/v1/public/feeds/news.xml
- Privacy: https://saas.aunoo.ai/legal/privacy · Terms: https://saas.aunoo.ai/legal/terms
- Security contact: https://saas.aunoo.ai/.well-known/security.txt

---


# Tool catalogue

28 tools, callable over MCP (`tools/call`) or REST (`POST /api/v1/skills/workspace/run`). Topic-scoped args are auto-filled from the key's allowed topics.


## Analysis


### `analyze_sentiment_trends` — Sentiment trends (read-only)

Aggregate sentiment trends over time


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Required — defaults to first allowed topic if omitted |
| `days` | integer |  | _(default: 30)_ |


### `forecast_sentiment_inflection` — Sentiment inflection forecast (read-only)

Forecast whether a topic's sentiment is about to turn — momentum, the most recent change-point (date + direction + size), and an inflection-risk flag with a projected sign-flip date. Computed (CUSUM change-point + slope), not summarized. Use it to tell whether the mood is steady, shifting, or about to cross from positive to negative (or vice versa).


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for the cross-topic 'Overall' mood. |
| `days` | integer |  | Lookback window for the sentiment series. _(default: 45)_ |


### `forecast_topic_trajectory` — Topic trajectory forecast (read-only)

Forecast a topic's lifecycle phase from its daily article-volume curve — emerging / accelerating / cresting / declining / dormant — with growth rate and, when a curve fits, a projected peak date and ceiling. Computed (logistic fit + momentum), not summarized. Use it to tell whether a story is still climbing or already past its peak.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for the cross-topic 'Overall' trajectory. |
| `days` | integer |  | Lookback window for the volume curve (needs enough points to fit). _(default: 45)_ |


### `get_consensus` — Consensus and outliers (read-only)

Return Aunoo's cached cross-source consensus analysis for a topic — 3-5 categories where coverage converges, with key insights and source breakdown. Refreshed by the foresight worker; falls back to the consensus_analysis recipe when cache is missing.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for cross-topic 'Overall' consensus. |
| `days` | integer |  | Best left unset. The analysis is pre-generated for a single fixed window (currently 7 days); other values are served from that same window, not recomputed. _(default: 7)_ |


### `get_foresight_component` — Foresight component (read-only)

Get Aunoo's ACTUAL in-app chart for a topic as a self-contained HTML document (same server-rendered SVG as the app + public share page: the S-curve with scenarios plotted on it, the H1/H2/H3 columns, consensus cards). kind='horizons' (Future Horizons) or kind='consensus' (Consensus & Outliers); pass a topic_id. Drop the returned `html` VERBATIM into an HTML artifact to show the exact same chart as the Aunoo UI — do not rebuild it. Pair with the future_horizons / consensus_outliers recipes.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `kind` | string · enum(horizons, consensus) |  | Which surface: 'horizons' (Future Horizons) or 'consensus' (Consensus & Outliers). _(default: horizons)_ |
| `topic_id` | integer |  | Topic id from the key's scope — the chart is per-topic (rendered from that topic's cached analysis). |
| `days` | integer |  | Best left unset; the analysis is pre-generated for a fixed window and served from it. _(default: 7)_ |


### `get_horizons` — Future horizons (read-only)

Return Aunoo's cached Three-Horizons foresight scenarios for a topic — current developments (H1), emerging shifts (H2), longer-horizon possibilities (H3). Cached; refreshed by the foresight worker.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for cross-topic Overall horizons. |
| `days` | integer |  | Best left unset. The forecast is pre-generated for a single fixed window (currently 7 days); other values are served from that same window, not recomputed. _(default: 7)_ |


### `get_polarization_index` — Polarization index (read-only)

Measure how far apart the left and right are framing a topic — a 0–100 score for how separable left- vs right-leaning coverage is in embedding space, plus a trend (widening / narrowing / stable) vs. the prior window. Computed (linear-probe AUC), not summarized. Use it to spot stories fragmenting into incompatible narratives; a widening gap is an early flashpoint signal.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for the cross-topic 'Overall' index. |
| `days` | integer |  | Window per side; the trend compares it to the prior equal window. _(default: 14)_ |


### `get_trust_signals` — Trust signals for an article (read-only)

The five per-article Trust Signals Aunoo shows in the app — ① Source (outlet bias / factual record / credibility) ② Claims (per-claim verdicts when the article has been validated, else how many other outlets carry the story) ③ Origin (AI-generated-content detection) ④ Spread (how many outlets republished it and whether one owner carries most of them) ⑤ Owner (who ultimately owns the outlet). Read-only and free: it reports what has already been measured and starts no new analysis. A signal with tone 'neutral' and rating '—' was NOT measured — that is not a clean result. Takes one article_id or up to 25 article_ids. To fact-check an article that has no claim verdicts yet, call validate_article; to see who else ran the story, get_story_coverage.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Article id — for a single article |
| `article_ids` | array |  | Up to 25 article ids, rated in one call |
| `window_hours` | integer |  | Look-back for the Claims and Spread republication counts _(default: 72)_ |


### `get_trust_signals_for_urls` — Trust signals for URLs (read-only)

The same five Trust Signals as get_trust_signals, for articles named by URL rather than by Aunoo article id — up to 25 urls. A URL Aunoo holds gets all five stations. Any other URL gets ① Source and ⑤ Owner rated from the outlet domain (Media Bias/Fact Check record, beneficial-owner map) and neutral ② Claims ③ Origin ④ Spread, marked in_corpus=false. Neutral means NOT measured, not clean. Read-only and free. Use this when you hold an article from elsewhere; use get_trust_signals when you have an Aunoo article id.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `url` | string |  | Article URL — for a single article |
| `urls` | array |  | Up to 25 article URLs, rated in one call |
| `window_hours` | integer |  | Look-back for the Claims and Spread republication counts (in-corpus articles only) _(default: 72)_ |


### `render_horizons_chart` — Render horizons chart (read-only)

Render the Three-Horizons foresight as a PNG chart — the same S-curve visual as the in-app Future Horizons page (current H1 declining, transition H2 cresting, future H3 rising) over a forward year axis. Returns an image the assistant can show directly. To EMBED the real chart in an HTML/JSX artifact, pass format='data_uri' — the response then includes image_data_uri, a data:image/png;base64 string you drop into <img src> (no need to recreate the chart). Use get_horizons for the scenario text.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for the cross-topic Overall chart. |
| `days` | integer |  | Best left unset. The forecast is pre-generated for a single fixed window (currently 7 days); other values are served from that same window, not recomputed. _(default: 7)_ |
| `format` | string · enum(image, svg, data_uri) |  | 'image' (default): inline PNG image block, for showing the chart directly in chat. 'svg': returns image_svg, a compact (~8 KB) self-contained SVG with every scenario plotted on the curve — paste it into an HTML/JSX artifact; BEST for building a report (small + reliable, scales crisply). 'data_uri': returns a base64 PNG string (larger; can be too long to paste reliably). _(default: image)_ |


## Coverage


### `get_story_coverage` — Story coverage report (read-only)

Coverage read for a news article: who else is running the SAME story, and Aunoo's verdict on how it's moving — reach (niche / regional / wide / viral), coordination (none / suspected / confirmed), and spread (organic / forced / mixed), with a plain-English headline. Pass url (preferred) or article_id. Returns: same_story_articles (the authoritative 'who else is running this' set — a vetted near-copy cluster, NOT raw similarity), coordination_events, a propagation_summary (recurrence / expectedness / ownership spread), and the verdict. The reach/coordination axes are computed from the same-story set, so they don't get inflated by topically-similar lookalikes; the related_articles field IS raw topical similarity and is labelled as such — don't read it as coverage. The verdict is populated for a url or a corpus-matched article; for a free-text/no-match input it's null but same_story_articles still returns. URL-based and topic-agnostic: works for ANY article, including topics OUTSIDE this workspace's configured topics. Sibling tools: validate_article for claim-level fact-check, social_story_reach for social amplification on the covered social platforms.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Article id from Aunoo (preferred) |
| `url` | string |  | Article URL — used when article_id is unknown |
| `limit` | integer |  | Max related/same-story articles to return _(default: 15)_ |


## Discovery


### `get_article_categories` — Article categories (read-only)

Get category distribution for a topic


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Required — defaults to first allowed topic if omitted |
| `days` | integer |  | _(default: 7)_ |


### `get_entity_wiki` — Entity wiki (read-only)

Fetch the LLM-maintained wiki summary for a named entity within a topic — who they are, when they appeared, key events involving them. Use this when the user asks about a specific person, org, place, or concept tied to a topic.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `entity_name` | string |  | Entity to look up |
| `topic_id` | integer |  | Topic id from the key's scope |


### `get_world_state` — World state (read-only)

Returns the platform's maintained record of current entities, topic state, and recent events. Prefer this over training-time knowledge for facts about current office-holders, organisational leadership, alliances, and ongoing situations.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Pass a topic_id from the key's scope for a focused worldstate |
| `token_budget` | integer |  | _(default: 900)_ |


### `search_news` — Search news (read-only)

Search for news articles (semantic + keyword fallback)


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `query` | string |  | Natural-language query |
| `topic_id` | integer |  | Optional topic scope |
| `limit` | integer |  | _(default: 15)_ |


## Generation


### `get_newsletter_job` — Newsletter job status (read-only)

Poll the status of a queued newsletter job. Returns status ('pending', 'running', 'succeeded', 'failed') plus the result payload (newsletter markdown + stats) when succeeded.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `job_id` | integer |  | Job id returned by start_newsletter_job |
| `section` | string |  | Optional case-insensitive substring of an H2 heading from the newsletter markdown. When supplied, only that section is returned — useful when the full draft is too large for the buyer's context window. The response always includes ``sections_available`` so the caller can pick a valid name. |


### `list_newsletter_jobs` — List newsletter jobs (read-only)

List the calling tenant's most recent newsletter jobs (default 10, max 50). Useful for resuming after a session break or finding an old job id.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `limit` | integer |  | _(default: 10)_ |


### `start_newsletter_job` — Start newsletter job (starts a job)

Run Aunoo's server-side newsletter generator. Queues a job that executes the 5-stage pipeline (fetch → score → sections → deep-dive → writer) and produces a complete markdown draft. Returns job_id immediately; poll get_newsletter_job(job_id) until status='succeeded'. Typical runtime 2-5 minutes.  **topic_id is required for a topic-scoped issue.** Pass a topic_id from your workspace scope (use list_capabilities to see topics_in_scope). Omitting topic_id is NOT 'pick one for me' — it runs the cross-topic 'Overall' newsletter spanning every Aunoo topic, which is usually NOT what the user asked for. topic_display alone is just the heading; it does not scope the article pool.  Distinct from the 'newsletter' MCP recipe (drafting playbook YOU run) and the 'newsletter' sampling preset (article selection only).


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id from the key's scope. Omit for cross-topic 'Overall' newsletter. |
| `topic_display` | string |  | Human-readable topic name used in the newsletter heading (auto-resolved from topic_id if omitted) |
| `days_back` | integer |  | Newsletter window in days _(default: 7)_ |
| `template_slug` | string |  | Optional saved newsletter-template slug. Omit for the free-form / 'auto' path. |


## Introspection


### `list_capabilities` — List capabilities (read-only)

Return a chat-friendly summary of what this Aunoo connection can do — packs in scope, tool catalogue, named recipes, and a 'how to get started' hint. Call this when the user asks 'what can you do' / 'what's available' / 'how do I get started'.


_No parameters._


## Retrieval


### `fetch_related_to_article` — Related articles (read-only)

Return articles semantically similar to a given article id via pgvector KNN.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Seed article id |
| `limit` | integer |  | _(default: 8)_ |


### `follow_up_query` — Follow-up search (read-only)

Combine previous context with new query results


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `query` | string |  | Follow-up natural-language query |
| `previous_context` | array |  | Articles already in the conversation context (passed back so dedup works) |
| `topic_id` | integer |  | Optional topic scope |
| `limit` | integer |  | _(default: 10)_ |


### `get_article_full` — Full article (read-only)

Fetch a single article by id with full content (no 2000-char truncation). Scoped to the api key's allowed_topic_ids.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Article id |


### `get_topic_articles` — Topic articles (read-only)

Fetch articles for a specific topic with optional sampling


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `topic_id` | integer |  | Topic id; optional if the key covers one topic |
| `limit` | integer |  | _(default: 30)_ |
| `days` | integer |  | _(default: 7)_ |
| `sampling_pipeline` | string · enum(all_topics_default, balanced_topics, bias_neutral, diverse, high_factuality, latest, newsletter, quality_first, semantic_search) |  | Optional article-SELECTION strategy (filter + sampler chain). Picks WHICH articles to return, not how to use them. Valid: all_topics_default · balanced_topics · bias_neutral · diverse · high_factuality · latest · newsletter · quality_first · semantic_search. Use 'newsletter' for a quality-gated deduped set you'll summarise; 'high_factuality' for MBFC-high outlets only; 'bias_neutral' for centre-leaning sources. Distinct from the MCP 'newsletter' RECIPE (prompts/get(newsletter)) — that's the multi-step drafting playbook, not a selection strategy. |


### `search_articles_by_keywords` — Keyword search (read-only)

Keyword search across title, content, and summary


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `keywords` | string |  | Keyword or phrase |
| `topic_id` | integer |  | Optional topic scope |
| `limit` | integer |  | _(default: 15)_ |


### `semantic_search_and_analyze` — Semantic search and analysis (read-only)

Vector search for semantically similar articles


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `query` | string |  | Natural-language query |
| `topic_id` | integer |  | Optional topic scope |
| `limit` | integer |  | _(default: 10)_ |


## Validation


### `get_validation_job` — Validation job status (read-only)

Poll the status of a queued validation job. Returns status ('pending', 'running', 'succeeded', 'failed') plus the full validation report (verdict, confidence, claims, corroboration, …) in result when succeeded.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `job_id` | integer |  | Job id returned by start_validation_job |


### `start_validation_job` — Start validation job (starts a job)

Queue an independent article fact-check as a background job and return a job_id immediately. Runs the same engine as validate_article but in the worker with no tool-window limit, so it completes reliably on large/complex articles (where validate_article can time out). Poll get_validation_job(job_id) every ~25 s until status='succeeded'. Typical runtime 1-2 minutes. Pass article_id (preferred) or url. URL-based: works for ANY article, including topics OUTSIDE this workspace's configured topics. Corroboration is corpus-bound — an off-topic story shows no corpus corroboration even if widely covered; read web_evidence for the open-web picture.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Article id from Aunoo (preferred) |
| `url` | string |  | External URL — used when article_id is unknown |
| `force` | boolean |  | Skip cache and re-run subagents _(default: False)_ |


### `validate_article` — Validate article claims (starts a job)

Run an independent fact-check on a news article: extracts claims, verifies each against source reputation, corroboration across outlets, external fact-check archives, and synthesises a verdict (e.g., 'corroborated', 'contested', 'unverifiable') with a confidence score. Runs inline with a ~25 s budget; subsequent calls on the same article hit the cache and return fast. For a large or claim-dense article that may exceed the tool window, prefer start_validation_job + get_validation_job (same engine, no time limit) — and if this tool returns a timeout, switch to the job tools rather than retrying. URL-based: works for ANY article, including topics OUTSIDE this workspace's configured topics (unlike the topic-scoped search tools). Note: corroboration is checked against Aunoo's indexed corpus, so an article on a topic Aunoo doesn't index shows zero corpus corroboration even when widely covered elsewhere — read the web_evidence field for open-web coverage, don't read empty corpus corroboration as 'uncorroborated'.


| Parameter | Type | Required | Description |
|---|---|:--:|---|
| `article_id` | integer |  | Article id from Aunoo (preferred) |
| `url` | string |  | External URL — used when article_id is unknown |
| `force` | boolean |  | Skip cache and re-run subagents _(default: False)_ |


# Recipes

Named multi-step playbooks. Fetch via MCP `prompts/get(name, arguments)` — the response is a set of instructions the calling assistant then follows, using the tools above.


### `deep_dive`

Research-style multi-angle dive on a question. Walks the buyer's assistant through grounding via WORLD STATE, primary article retrieval, entity wikis, full-body fetch, and Aunoo's Deep response format (400-800 words, 3+ sources).


| Argument | Required | Description |
|---|:--:|---|
| `query` | ✓ | The user's question to research. |
| `topic_id` |  | Topic id from the key's allowed scope. Defaults to the first allowed. |


### `consensus_analysis`

Identify 3-4 consensus categories where coverage converges + where it diverges. Cross-source synthesis for news consumers.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. |
| `days` |  | Time window to analyse (default 30). |


### `future_horizons`

Standardized, VISUAL Three-Horizons foresight for a topic: pulls get_horizons + the canonical S-curve, then renders Aunoo's future-horizons component as an artifact (HTML/text fallback). Use this to SHOW horizons, not just describe them.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. |


### `consensus_outliers`

Standardized, VISUAL Consensus & Outliers for a topic: pulls get_consensus, then renders Aunoo's consensus component (sentiment mix + agreement + minority outliers) as an artifact (HTML/text fallback). Use this to SHOW consensus, not just describe it.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. |


### `foresight_report`

Build ONE cohesive, on-brand report artifact for a topic — orchestrates the full foresight set: the Three-Horizons chart (Aunoo SVG) + scenarios, the computed volume / sentiment / polarization signals, and Consensus & Outliers, assembled into a single React/HTML report. Use this for a COMPLETE report; the per-surface recipes (future_horizons, consensus_outliers) each cover one section.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. |


### `newsletter`

Multi-step playbook for drafting a topic-scoped newsletter in Aunoo's house voice. Plans 5-8 sections, deep-dives one, assembles markdown with inline citations. Distinct from the 'newsletter' SAMPLING preset on get_topic_articles (which only selects articles), and from start_newsletter_job (server-side generator that produces the final draft). Use this recipe when YOU (the assistant) are doing the drafting; use start_newsletter_job when you want Aunoo's generator to produce the draft.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. |
| `style` |  | Voice preset: atlantic \| brief \| weird (default atlantic). |
| `audience` |  | Audience hint, e.g. analyst \| executive \| builder. |


### `correspondent_brief`

Short-form briefing (200-300 words) in the voice of a named Aunoo correspondent persona. Pulls fresh articles matching the persona's signal, evaluates each against the persona's mandate, surfaces top matches with excerpts.


| Argument | Required | Description |
|---|:--:|---|
| `persona` |  | One of: escalation_monitor, zero_day_tracker, ai_regulation_watch, market_disruption_alert, quantum_breakthrough_detector. Defaults to ai_regulation_watch. |
| `topic_id` |  | Topic id from the key's allowed scope. |


### `forecast_brief`

Forward-looking outlook for a topic built from Aunoo's three COMPUTED forecast signals: volume trajectory (lifecycle phase + projected peak), sentiment inflection (is the mood turning, with a projected flip date), and narrative polarization (are left and right diverging). Grounds each in current coverage and synthesises a short observational brief. Distinct from get_horizons (scenario narratives) and consensus_analysis (current convergence) — this reads the trend lines and says where they point.


| Argument | Required | Description |
|---|:--:|---|
| `topic_id` |  | Topic id from the key's allowed scope. Defaults to the first allowed. |
| `days` |  | Lookback for the trajectory + sentiment signals (default 45; polarization always uses 14). |


### `investigation`

Rigorous, evidence-first investigation + fact-check of a claim, article, or URL. Grounds via WORLD STATE, gathers primary sources, then runs Aunoo's claims validator — including the correct async path (validate_article inline; on timeout, start_validation_job + poll get_validation_job) — weighs provenance (independent corroboration vs syndication), and delivers a verdict with confidence and caveats. Distinct from deep_dive (synthesis, no fact-check) — this one adjudicates.


| Argument | Required | Description |
|---|:--:|---|
| `subject` | ✓ | The claim, article, or URL to investigate and fact-check. |
| `topic_id` |  | Topic id from the key's allowed scope. Defaults to the first allowed. |
| `depth` |  | quick \| standard \| deep (default standard) — controls how many primary sources to pull. |


### `story_reach`

Trace how a story spread on the covered social platforms and how it was received, and present it as a structured reach card (Spread → Top amplifiers → Reception). Wraps social_story_reach (quick) or start_social_reach_job + get_social_reach_job (deep: follower-weighted reach, fresh-account surge, coordination cohorts, reply reception). Needs the Social module on this connection. Observational — reach/reception are evidence, not a per-account verdict.


| Argument | Required | Description |
|---|:--:|---|
| `subject` | ✓ | The article URL to trace across the covered social platforms. |
| `depth` |  | standard \| deep (default standard) — deep adds follower-weighted reach, fresh-account surge, cohorts, and reply reception via the async job. |