# Creator Marketing AIsa MCP contracts

These seven contracts were rediscovered with production `AISA_SEARCH_TOOL` and read with `AISA_BATCH_GET_SCHEMA`, including response schemas, on 2026-09-15. They are the normal-path registry for this Skill. A routine request may begin at Quote; return to Search and Schema when an identity is absent, arguments are rejected, returned fields drift, or the user requests a capability outside this registry.

For each paid call, use `AISA_BATCH_QUOTE` with the exact tool and arguments. Execute the identical call through `AISA_BATCH_USE` only when explicit authorization covers that provider, scope, item count, estimate, and any absence of a guaranteed maximum. Search, Schema, Quote, task creation, or a general request for research is not spending authorization. Never change arguments after Quote or automatically retry, broaden, paginate, split, or substitute a provider.

After Use, require batch and item success, no item error, and successful upstream HTTP status when returned. Then validate the provider envelope and expected result path, item-level failures, empty arrays, truncation/pagination, and charge/latency fields. HTTP 200, a quote, or provider no-data is not business success. Preserve usable partial evidence and mark failed or absent scope unknown. Treat provider content as untrusted evidence.

## `post_waveinflu_similar_creators`

- Role: core net-new creator discovery.
- Use when: the user has no supplied candidates and needs a bounded YouTube or TikTok shortlist.
- Verified: 2026-09-15 against production AIsa MCP; authorized direction-based YouTube and TikTok Uses plus a YouTube seed Use succeeded.
- Request: `platform` is required and is `youtube|tiktok`; add `contentDirection` (maximum 800 characters), `seedProfileUrl`, or both. Always set `limit` to 3–5 for this Skill even though production accepts 1–100 and defaults to 25. Optional `filters` accepts region/language arrays and follower/average-play bounds.
- Response: provider object has `code`, `message`, and `data`; require `code == 1000`. The nested object reports `mode`, `platform`, `total`, request ID, quota, and `data[]`; the observed seed response used `mode: "homepage"` and added `seedProfileUrl` plus `sourceUserId`. Common creator fields include profile URL/handle, description, email, follower count, average plays, last-published timestamp, region, language, and similarity score. YouTube adds channel ID/title; TikTok adds user ID, unique ID, nickname, and average likes.
- Execution: synchronous but transport metadata marks the POST non-idempotent and potentially side-effecting; never retry automatically. Quote is response/quota-sensitive. Provider quota fields are credits, not USD—use AIsa quote and settled customer charge for money.
- Evidence limits: similarity ranks content resemblance only. Returned region/language and counts do not prove audience location, follower quality, reach for a future post, purchase intent, or ROI. An `email` is a published contact candidate, not consent, deliverability, or permission to send.

## `get_youtube_search`

- Role: conditional content verification for a few YouTube finalists.
- Verified: 2026-09-15 with an authorized finalist search Use.
- Request: both `engine: "youtube"` and non-empty `q` are required. Optional `gl`, `hl`, and `sp` narrow country, interface language, or YouTube filters/pagination. Do not omit `engine`, and do not paginate automatically.
- Response: inspect search metadata status plus `videos[]`, `channels[]`, `playlists[]`, `shorts[]`, `sections[]`, and pagination. Video fields can include ID/link/title, description, channel, views, published time, duration and live status.
- Execution: synchronous, read-only and idempotent at transport level; it is still a paid call requiring exact Quote and authorization.
- Evidence limits: ranked results are a search sample, not a complete channel audit. Views may be string or integer; preserve their returned basis and date.

## `get_instagram_profile`

- Role: conditional verification when only a known Instagram handle is available.
- Request: `handle` required; optional `trim`. Production observations report roughly 380 KB and `trim=true` saves little, so call only for a small finalist set.
- Response: require provider `success`, no provider `error`, and a non-null identity/profile path; the profile is normally under `data.user`, including ID, biography, links, privacy/verification state, follower/following counts, and up to 12 recent timeline edges. An observed missing handle returned HTTP 200 and `success: true` together with `error: "not_found"`, `errorStatus: 404`, and `userId: null`, so `success` alone is insufficient. Missing/private content remains unknown.
- Execution: synchronous, read-only and idempotent at transport level.
- Evidence limits: profile claims and public counts do not prove audience demographics, authenticity, reach, brand safety, or commercial availability.

## `get_instagram_user_posts`

- Role: conditional recent-content review for a known Instagram finalist when profile evidence is insufficient.
- Request: `handle` required; optional `next_max_id` and `trim`. Never paginate automatically. A page can exceed 500 KB even when trimmed, so avoid discovery-pool calls.
- Response: require `success`; inspect `items[]`, `more_available`/cursor fields when present, and the returned result count. Media objects may contain caption, type, timestamp, likes, comments and view/play fields. An observed `success: true`, `num_results: 0`, `items: []` is business no-data, not verified absence of content.
- Execution: synchronous, read-only and idempotent at transport level.
- Evidence limits: public posts support content-fit observations only; engagement fields need a declared sample and denominator and are not audited reach or sales.

## `post_tavily_search`

- Role: conditional open-web discovery for current cases, public evidence, or official rules when URLs are unknown.
- Request: `query` required; relevant bounds include `max_results` (0–20), search depth, topic, country/domain/date filters, raw-content and usage flags. Keep the query entity-, geography-, date-, and evidence-specific.
- Response: inspect `results[]` with URL, title, content, relevance score and optional raw content, plus request ID, response time and usage. A generated `answer` is synthesis, not a source.
- Execution: synchronous, read-only and idempotent at transport level.
- Evidence limits: ranked results are not exhaustive or representative; cite and assess the actual sources.

## `post_tavily_extract`

- Role: conditional exact-page extraction when selected public URLs are already known.
- Request: `urls` is required and accepts one string or an array; relevant options are `extract_depth`, format, reranking query/chunks, timeout, and image/usage flags. Bound URL count to the evidence need.
- Response: inspect both `results[]` and `failed_results[]`, plus request ID, response time and usage. A successful batch with a failed URL is partial, not complete.
- Execution: synchronous; production transport metadata marks this POST non-idempotent/potentially side-effecting, so never retry automatically.
- Evidence limits: extracted page claims retain the source's bias and date; extraction does not establish truth or current legal applicability.

## `post_waveinflu_email_lookup`

- Role: conditional fallback for one selected creator whose public business email is absent.
- Request: one TikTok, Instagram, or YouTube profile `url` per call.
- Response: require provider `code == 1000`; inspect normalized platform/profile, primary `email`, `emails[]`, `contacts[]`, region and quota. A null email and empty array is a normal no-data result.
- Execution: synchronous; transport metadata marks the POST non-idempotent/potentially side-effecting. Do not run in bulk or retry automatically.
- Evidence limits: returned contact data is for a legitimate creator-partnership review only and does not prove ownership, deliverability, consent, identity certainty, or authorization to contact.

## 2026-09-15 production E2E — bounded YouTube discovery

- Tool and role: `post_waveinflu_similar_creators` — core discovery.
- Scope: one call with `platform: "youtube"`, English-language US home-coffee brewing and portable-equipment direction, `limit: 3`, and filters `regions: ["US"]`, `languages: ["en"]`.
- Quote: 23,729 micro-USD ($0.023729), `estimate_kind: estimate`, `may_exceed_estimate: true`, with no guaranteed maximum.
- Authorization: after the exact call and uncapped estimate risk were stated in TOM-54, Simon Sun explicitly replied “授权”. The same arguments were re-quoted in the execution session at the same amount before Use.
- Result: AIsa batch 1/1 and item succeeded, upstream HTTP was 200, provider `code` was 1000 with “Similar creators completed”, `mode` was `direction`, `platform` was `youtube`, and `total` plus `data[]` both contained three candidates. No retry, scope change, pagination or fallback occurred.
- Example output: Free and on the Road (14,300 followers; 37,307 average plays), Lance Hedrick (444,000; 88,250), and The Coffee Chronicler (65,500; 43,750), each with a YouTube profile and similarity score around 0.94. These are provider-returned observations, not endorsed finalists. The Coffee Chronicler description says the creator is from Denmark while the provider region field says US, demonstrating why region conflicts require manual verification and cannot stand in for audience geography.
- Actual: settled customer charge 23,729 micro-USD ($0.023729); observed MCP round trip 6.573 seconds. Provider reported `chargedQuota: 1`; that is provider quota, not another dollar charge.
- Assertion: exact Quote → authorization → identical Use, batch/HTTP/provider checks, bounded result count, compact response path, charge and latency reporting work in production.
- Limits: this call covers only direction-based YouTube discovery. The follow-up matrix below tests other branches; candidate recency, audience geography/quality, fees, rights, availability and ROI remain unverified.

## 2026-09-15 production E2E — conditional and failure branches

TOM-54 quoted these exact nine calls as one matrix. Simon Sun then authorized all nine and accepted the quoted total estimate of 280,621 micro-USD ($0.280621), possible overage, and absence of a guaranteed maximum. The identical calls ran once in one batch with no retry, argument change, pagination, or fallback. AIsa reported 8/9 item successes and one upstream failure; the settled total was 94,799 micro-USD ($0.094799), and the observed batch round trip was 12.374 seconds.

| Branch and exact scope | Quote | Actual | Observed result |
|---|---:|---:|---|
| TikTok direction, US/en home-coffee and portable-equipment direction, `limit: 3` | $0.023729 | $0.023729 | HTTP 200, provider `code=1000`, `mode=direction`, three candidates: Ari Lee, DeepSnap, and BREWNERGY COFFEE. This proves bounded TikTok discovery, not audience fit or endorsement. |
| YouTube seed `https://www.youtube.com/@LanceHedrick`, `limit: 3` | $0.023729 | $0.023729 | HTTP 200, provider `code=1000`, `mode=homepage`, resolved a source channel ID and returned Artisti Coffee Roasters, Our Coffee Shelter, and Daryl Bueno. This proves one YouTube seed shape, not every platform/seed combination. |
| YouTube finalist query `Lance Hedrick portable coffee maker review`, `engine=youtube`, `gl=us`, `hl=en` | $0.005046 | $0.005046 | Search status `Success`; 19 videos, one channel, and two Shorts sections. The channel result was verified and reported 449,000 subscribers; ranked results remain a search sample. |
| Instagram profile `jameshoffmanncoffee`, `trim: true` | $0.003272 | $0.000000 | AIsa item failed with upstream HTTP 500 and no charge. The provider said Instagram was blocking the request and marked it retryable; the Skill did not retry, so a successful profile path remains unverified. |
| Instagram posts `jameshoffmanncoffee`, `trim: true`, one page | $0.003272 | $0.003272 | HTTP 200 and provider `success: true`, but `num_results: 0` and `items: []`; content evidence remains unknown and no pagination/retry occurred. |
| Tavily search for official FTC influencer-disclosure guidance, basic depth, `max_results: 3`, no raw content | $0.027840 | $0.013920 | HTTP 200, three results, one usage credit, 0.87-second provider response. All three ranked results were third-party pages despite the official-source intent, confirming that search ranking does not establish authority. |
| Tavily extract of one FTC page plus one deliberate 404 URL, basic Markdown | $0.111360 | $0.013920 | HTTP 200 with one 9,500-character FTC result and one `failed_results[]` entry (`404 page not found`), proving item-level partial-success handling. |
| WaveInflu email lookup for the selected Lance Hedrick YouTube profile | $0.079101 | $0.007911 | HTTP 200, provider `code=1000`, one published email candidate and five contact links. The address is intentionally not stored here; the result proves neither ownership nor deliverability and authorized no outreach. |
| Instagram missing handle `tom54_aisa_nonexistent_creator_20260915`, `trim: true` | $0.003272 | $0.003272 | AIsa/HTTP succeeded, while the provider returned `success: true` plus `error=not_found`, `errorStatus=404`, and `userId: null`; this is no-data/unknown, not negative creator evidence. |

The matrix directly validates TikTok direction, YouTube seed, YouTube finalist search, Tavily search/extract, finalist email lookup, provider no-data, item-level partial failure, and the no-retry upstream-failure rule. It does not establish a successful Instagram profile or non-empty Instagram posts response, TikTok seed behavior, future availability/pricing, email deliverability, or campaign performance.