Source research tool reference

The direct HTTP client and remote MCP tools call the same externally executed workflow. Ducket runs no model reasoning on this path.

Current workflow contract

The former Preview workflow is current for every authorized Source user. Historical assignments are read-only and do not select behavior. Organization membership, Source scopes, report grants and author ownership remain required.

Selected capabilities and authenticated MCP discovery expose source_workflow_read, source_workflow_continue and source_workflow_step. Direct HTTP uses workflow_read, workflow_continue and workflow_step at the existing v1 action route. Discovery includes the promoted coordination tools and guidance. Workflow version argus-workflow-preview-v1 is separate from the research method hash and purchased policy.

workflow_continue accepts session_id, operation_id, expected_revision, brief_version and an optional commercial_objective: sponsorship_pipeline, exhibitor_sales, brand_awareness, customer_engagement, exploratory or unspecified. It records deliberate continuation of the same confirmed session and event. It creates no allowance, report, supplier call or native task. Existing saved methods remain bound.

workflow_read accepts session_id, run_id, optional account_key, kind and one optional recipient_user_id or recipient_email. It uses workspace_read, company_context, company_report and outreach_read readers for current report applicability, drafts and sharing. A handoff link appears only when existing deliberately shared content is readable by the named recipient. The member handoff check sends teammate email in an authenticated POST body; email in a GET URL refuses recipient_body_required. Private work stays private. An omitted recipient returns recipient_not_checked when shared work exists.

workflow_step accepts the published bounded schema for host capability, contact lookup, failure or resumption. It records host assertions with external_unverified provenance, never independently verified supplier success. Search and enrichment are distinct. A claimed match requires exact company-domain agreement and a current commercial function and region with a timezone-stamped observation no older than 30 days. Budget ownership remains unverified. Names, email addresses, phone numbers, CRM records and supplier output have no fields in this contract.

Workflow coordination is available without enrollment. Contact outcomes with insufficient observed authority refuse host_authority_unobserved; ambiguous timeouts retain host_lookup_uncertain. Revision, idempotency, technical bounds and tenant refusals remain enforced. No paid replay, sending or publication is authorized.

Reconnect or refresh capabilities after a version change. Server checks on every action override a stale tab or cached tool definition. An already-admitted operation retains its original accounting and settles once. Saved company reports, evidence and unsent drafts remain available through their authorized stable readers.

The existing account connection auth_type value terminal identifies direct API keys; the interface labels these API key. OAuth connectors retain auth_type oauth.

Workflow capabilities adds prepared_events from the current member and organization permissions. Each item contains run_id, event, edition, workspace_path, choice and owned saved_sessions. After the user chooses continuation, read an existing saved session before creating a draft. An empty list grants no prepared-event access. Setup includes the prepared choices only when present and always waits for input. Explicit company tasks and resume instructions take precedence. This read creates no session, confirms no brief and buys no research. Foreign organizations and removed memberships refuse before disclosure.

OAuth is primary for Claude and ChatGPT. Advanced private HTTP setup under Another agent includes your private, organization-scoped API key and environment HTTPS origin. Configure it privately and never repeat it in logs, URLs, screenshots or tracked files. Fetch the full quickstart and probe actual authenticated HTTP capability. Direct access needs no OAuth connector. Optional Source-only skill installation preserves project guidance. The settings-based OAuth/MCP path uses Source discovery, organization consent and the exact /source-mcp audience; refresh cannot widen scopes or change resource, and revoking a grant blocks its access and refresh tokens.

Pasting private setup text does not configure a process environment. Load the exact key into the requesting process or private secret store. Prefer the published client.py: it checks credential format before HTTP and constructs the Bearer header. Python subprocess argument lists do not expand environment-variable names; pass the configured environment to child processes. Never put an expanded key in curl arguments. A missing or malformed local credential must be fixed before the capabilities request. A 401 alone does not prove revocation. Reconnecting preserves saved work and separately authorized supplier spending.

Connection verification amendment, 2026-10-23: capabilities returns organization (id/name) and permissions from the authenticated principal. The account reader adds connection_stage and verified_at. OAuth without tool proof is access_authorized; privately issued keys start at setup_started. Only successful tool execution marks connection_verified. Handshake, discovery, malformed or refused tools and mailbox state confer no verification. Existing Source activity predating this tool proof requires re-verification. A single metadata-only connection_verification receipt reuses the operation journal with no session, supplier, allowance or research charge. Legacy status values remain for compatibility.

Connection and contract

The machine-readable quickstart is https://api.ducket.io/agent/quickstart. Exact versioned JSON schemas are published at https://api.ducket.io/agent/schema/v1 and in MCP tool discovery. HTTP operations use POST /api/source-agent/v1/{operation} with a Source bearer credential. The remote endpoint is /source-mcp.

• source:read: capabilities, resume and saved evidence.
• source:write: sessions, brief versions, candidates, research, report saves and unsent outreach draft saves.
• source:tools: server retrieval and supplier requests.

Structured connected reports, added 2026-10-20

Prepared customer publications keep their selected progress and exact report versions. Later workspace or report saves do not widen that published selection.

workspace_read / source_workspace_read reads the full authorized event company list, including prepared rows and agent additions. Supply run_id and offset; follow next_offset. Company context includes owned saved_sessions and saved documents. It creates no work and buys no research.

Team-read amendment, 2026-10-21: an authorized workspace read can include colleagues’ explicit workspace saves from the same organization. The optional connected_progress.source_author field gives display attribution. Shared projections keep private session locators empty and raw evidence lists empty. Ready saved report documents retain deliberate source quotations and dates. Their original context stays attached; applicability to another author’s brief is unconfirmed. Session briefs, drafts, raw evidence, credentials and conversations remain personal. These shared reads create no session, purchase, supplier call or report grant. Missing owning membership or a foreign parent refuses workspace_unavailable (404). Existing source:read, author-context and publication checks still apply to connected tools; a team read does not authorize a colleague’s private session or any write. Native report, dossier, evidence and export grants remain separate.

report_save / source_report_save writes a company report independently of native assessment slots. Supply session_id, operation_id, expected_revision, brief_version, run_id, account_key, candidate_id, kind (sponsorship or exhibiting), state (draft or ready), sections and claims. Sections are commercial_fit, relevant_buyers, participation_angle, supporting_sources, uncertainties and next_steps. A draft requires at least one nonempty section. Ready requires every section and an exact attributed company fact quotation. Unknown commercial facts remain explicit. Structural validation does not certify evidence quality.

Claims use kind fact or inference, text, evidence_id, quote and purpose. Facts require text to equal the saved quote; historical sources keep purpose historical. Sources must belong to the same session and candidate. External material remains independently unverified. Resume lists documents; read document_id to recover one immutable version in a fresh conversation. Every new save uses the latest session revision and a new stable operation ID. Exact retries reuse the saved document. No description or summary is written.

Current author, organization, event and company access, a confirmed brief, evidence checks and technical request bounds govern connected saves. Commercial evaluation expiry or exhaustion does not block host work. Revoking Source access still blocks new writes. Supplier funding and native slots are separate.

Invalid or empty writing returns invalid_arguments (422); wrong company/source, stale brief/revision and exhausted storage return their named refusals without replacing valid work. Interrupted writes roll back. The member GET /api/source-agent/account/companies/{run_id}/{account_key}/reports serves owned versions under no-store. Saved URL opens the ordinary company report. Earlier supplemental exhibitor actions retain their original permission checks.

Effective event brief

Each author has one effective confirmed context per organization and event. read, workspace_read and company_context return event_context and event_revision. Session reads also return effective_brief and effective_brief_version separately from that conversation’s own brief. A session draft does not supersede confirmed context. expected_revision protects the session; expected_event_context protects against another conversation or tab changing the event. A conflict returns event_context_conflict (409) without writing. Stale prepared provenance retains prepared_source_changed. Changing an already bound event identity returns event_identity_changed; create a separate event explicitly through the confirmed-event workflow.

The authenticated member GET /api/source-agent/account/workspaces/{run_id}/brief returns brief, brief_version, confirmed, event_context, event_revision, session_id, revision, optional draft, history, original_brief and editing availability. It writes nothing. POST on the same route accepts operation_id, expected_event_context, session_id with expected_revision when present, mode draft or confirm, and changes containing only description, audience, inventory or exclusions. Partial updates preserve unrelated facts and document references. Confirmation uses the existing connected writer in one transaction. Exact retries recover the saved request; saved_event_context identifies that request if a newer confirmed brief is now shown.

Partial changes apply over the saved draft when present, otherwise over the effective confirmed brief. Omitted fields preserve that baseline. Build the patch against the same loaded baseline: reverting a saved draft field requires sending its desired confirmed value explicitly, including an empty string or exclusions list when appropriate. An empty changes object confirms the existing draft; it does not discard it. Session revision and event-context checks still apply.

Both routes require current author, organization and event access and use no-store responses. Writes require current Source editing permission and retain the 300,000-byte request, saved-brief storage and revision bounds. Missing permission returns brief_edit_unavailable (403); stale context or revision returns 409; unsupported fields return invalid_arguments (422). No event, research job, supplier call, allowance reset or prepared-publication mutation follows. Drafts leave report applicability tied to confirmed context. Historical reports remain readable and confirmed context changes require review. Temporary what-if questions remain read-only. Native paid requests remain bound to their purchased original policy. A different author-effective brief returns native_brief_context_changed (409) before dispatch; an unconfirmed draft does not trigger that refusal. Revised native execution needs a separately reviewed binding.

Operations

• capabilities / source_capabilities: method binding, research topics, commercial blocks and workflow instructions. Optional extraction and method sections return bounded instructions with next_offset. Candidate tool schemas contain the exact extraction fields. The business method's hosted runtime and legacy budget defaults do not apply to this mode.
• create / source_create: stable operation ID and declared client/model metadata.
• company_context / source_company_context: read one authorized prepared event and company, with existing sources. This neither confirms a brief nor grants research.
• exhibitor_context / source_exhibitor_context: recover a currently authorized prepared company, confirmed event and saved source handles under an explicit company-scoped permission. No retrieval is purchased.
• exhibitor_assessment / source_exhibitor_assessment: save six assessment sections and exact saved-source claims for that company. Current Source access, the correct event/company binding and evidence validation are required. It buys no supplier calls, completes no native attempt and publishes no company.
• read / source_resume: saved state, outstanding work, operations and known or unknown supplier costs.
• operations / source_operations: recover saved supplier results and evidence handles after a lost reply. Send session_id and offset (default 0); follow next_offset until null. Pages contain at most 20 summaries. Requires source:read and the owning account and organization. Recovery makes no supplier request.
• brief / source_brief: save a corrected brief or explicitly confirm its version. Omitted optional fields retain saved values; explicit empty values clear them. Use expected_event_context when rebasing across conversations, alongside session expected_revision.
• tool / source_tool: search, public page read or licensed Argus query. No hosted extraction.
• candidates / source_candidates: useful batches with evidence handles and attributed offering extractions.
• research / source_research: request external company research and incrementally save findings and commercial blocks.
• report / source_report: validate required work, then save a report revision.
• evidence / source_evidence: read a bounded saved passage using an opaque evidence handle.

POST /api/source-agent/v1/create
Authorization: Bearer <Source connection key>
Content-Type: application/json

{"operation_id":"my-first-session-001","client":"terminal-agent","model":"declared"}

Mutations include the session ID, current expected revision and stable operation ID. Research also binds the confirmed brief version and company. Reports contain the existing five sections and separate outreach draft. Completion is computed from saved work. Clients cannot set admitted, verified, complete or independently reviewed flags.

Brief exclusions are exact company names. Put preference explanations in description; a sentence containing a company name does not match that company as an exclusion. Saved investigations let a current held company save supported findings and commercial writing. Saving preserves held status and does not complete a report, certify writing, buy research or authorize outreach. The member view opens as Assessment in progress.

Save and continue an incomplete assessment

Read with only session_id to discover investigations. Each summary carries research_id, name, candidate_id, brief_version, current_brief_version, research_revision, state, current, binding_status, saved_binding, has_content, readable and saved times. Read the session with section investigations and next_research_offset to continue the manifest; subsequent pages use next_offset. Pages contain at most 20 entries, including earlier briefs.

Select research_id for an overview: saved topic and block names, missing_topics, unknown_topics and unfinished_topics. Recommendation is the client's saved proposal. It grants no completion or qualification. Select section findings and offset 0, then follow next_offset for one complete finding and its citations per page, with text and exact quotes up to 4000 characters in both HTTP and MCP. Select block and offset 0 for 1600-character writing chunks. Follow next_offset until null. Research, candidate and report IDs are exclusive selectors. A block cannot combine with another section. Offsets above 100000 refuse read_offset_out_of_range.

Select section presentation for a read-only view through the shared report composer. It creates no report row. Views over 300000 UTF-8 bytes refuse presentation_too_large; findings and block pages still recover all original content. A malformed old record refuses research_integrity_failed; its summary says readable false and needs_reassessment. Missing old bindings also need reassessment. No content is silently truncated.

An incomplete view can withhold invalid offer wording or internal research language while showing supported findings and safe writing. withheld_sections names affected portions; presentation_issues preserves the original composition issues. The view says writing needs revision. Original blocks and findings stay recoverable unchanged. The completed-report path still validates the full original work and refuses its unresolved issues.

Brief corrections retain earlier research with its original company and brief. Changed qualification, identity or method bindings make conclusions need reassessment. Historical reads confer no write access. Saving current work requires an explicit current update; earlier research is never copied forward automatically. Topic and block updates replace their values within that brief's research record. Earlier briefs and operation history remain, without per-keystroke history.

POST /api/source-agent/v1/read
Authorization: Bearer <Source connection key>
Content-Type: application/json

{"session_id":"<saved session reference>","research_id":"<research ID from investigations>","section":"findings","offset":0}

Members use their existing signed-in account to open GET /api/source-agent/account/sessions/{session}/investigations/{research}. The sibling investigations reader accepts offset for the manifest. Both enforce the session owner, organization membership and current evaluation access. Reads need source:read; historical reading never grants source:write. No source retrieval or mutation is required for recovery.

The signed-in session reader GET /api/source-agent/account/sessions/{session} also returns the authorized org_id for the organization breadcrumb. Saved member links may carry ?org= as a navigation hint. It cannot select a session owner or change the reader's permission checks. The terminal and MCP session contracts are unchanged.

Read with session_id and candidate_id to recover that current company's candidate object, evidence_ids, schema-shaped extraction and qualification_revision. extraction_state is saved_client_input, partial_saved_input or invalid_saved_input. This is the client's saved input. Independent review has not been performed. Recovery uses the qualification parser: malformed optional fields are dropped while valid siblings survive, with refusals showing dropped fields. Invalid envelopes return an empty extraction. Unknown fields are omitted. Foreign sessions and historical candidate IDs are refused. Recovery makes no supplier request.

Authenticated multipart POST /api/source-agent/documents transforms supported organizer documents using the shared 25 MiB bound. The returned text belongs in the organizer brief; it cannot impersonate public company evidence. Configured deployments publish their canonical API and saved-session addresses, without using a request's Origin as a trusted destination.

Event workspace binding

Brief confirmation returns workspace_binding with the real run_id, engagement_id, organization, session and brief version. A new event creates an owned event workspace with zero native research budget. Exact event name, edition, city and country reuse one workspace within the organization. Multiple conversations retain separate history on that workspace. The existing evaluation event cap applies before creation. No native policy, publication, job or assessment permission is created.

The authenticated member endpoint GET /api/source-agent/account/workspaces lists authorized events and grouped conversation links. Opening a connected event reads organization-authorized saved company work. A team projection rechecks current membership, owned engagement and saved-record integrity. Private session access still requires the author’s individual Source permission. Native mutation routes remain unavailable. Existing workspace_save uses the confirmed binding, current revision and evidence; ordinary replay, identity and assessment-permission checks still apply. Another member receives no access to private session evidence through this index.

When information or tools are missing

The connected skill and capability instructions ask the agent to name the specific missing input or capability, offer a concrete next step and complete supported work. It should ask selectively for organizer-held audience details, current inventory, dated proposals, sponsor history or authorized relationship notes. Unknown sponsor budgets or contacts alone do not reject a company. Role suggestions and commercial angles remain hypotheses until supported.

Suggest another tool only when it materially helps, explain what it enables and check actual host availability and permissions before use. External costs remain separate from Argus allowances. Private CRM ingestion into Argus is unsupported. Guidance confers no purchase, sending, private export or retry permission. Schema validation does not establish research quality.

Prepared event references

The additive evidence-only exhibitor contract returns exhibitor_assessments in a session read. Resume with session_id, discover the assessment id, then read with exhibitor_assessment_id. The full bounded sections and claims are returned without new retrieval. Company-linked writing is labelled as agent analysis; independent review, eligibility and current booth availability remain unresolved. A changed brief, method, company reference or qualification leaves the saved writing readable with applicable false. Current Source access, confirmed event, company identity and exact evidence remain required. Commercial allowances and supplemental permissions do not govern this evidence-only save. No base evaluation or native attempt is reset. A changed binding refuses with prepared_source_changed.

The signed member interface can preview GET /api/source-agent/account/prepared/{run} and POST to the same address with its returned binding. It needs both the prepared workspace permission and current per-user Source access. The POST creates one unconfirmed draft for that user, organization and binding. Duplicate retries reuse it. Preview and handoff make no supplier call.

A handed-off brief includes prepared_origin: publication_id, run_id, brief_version_id, source_fingerprint, sample_sha256, public_brief_sha256 and event_facts_sha256. These identify the reviewed public event summary and the exact copied event header facts. Prepared companies, reports and private notes are excluded. Corrections retain that reference. A source change before confirmation returns prepared_source_changed and requires a fresh reviewed handoff. A confirmed session retains its own saved brief. The reference grants no report access.

Adapt to your agent's tools

The 2026-10-19 candidate adds plan / source_plan. Send session_id, optional candidate_id and up to ten client_capabilities. Each item has capability (company_discovery, public_page_retrieval, contact_lookup, crm_read or document_extraction), tool_name and availability (declared, client_demonstrated or unavailable). These remain client assertions. Declared tools require an actual host availability and permission check; only client_demonstrated selects an external-tool plan step. That still grants no authority to execute or spend. Resubmit the current set on resume. Plans recover saved evidence first and state required permissions and cost responsibility. Planning buys nothing.

The host invokes external tools under your existing permissions and charges. Availability does not authorize purchases, sending, contact exports or private-data transmission. Argus cannot inspect subscriptions, proxy arbitrary MCP servers or control their spending. Missing tools never authorize a paid fallback. Qualification requirements stay unchanged.

Save connected companies in Argus

The local candidate adds workspace_save (MCP source_workspace_save) under existing source:write. Supply session_id, operation_id, expected_revision, brief_version, run_id, candidate_id, kind sponsorship or exhibiting, progress_state proposed, researching or needs_verification, and summary. The confirmed session must bind that authorized existing event. The candidate needs saved evidence. Code resolves identity and refuses conflicting domains. A successful save returns workspace with the stable event account, source handles, snapshot hash and URL; read returns workspace_progress for resume. These are agent claims, with independent review pending. There is no new supplier or assessment authority. Technical request and rate limits apply; saved replay is free. Existing prepared and platform records remain unchanged. Explicit saved company progress and ready reports are readable by authorized teammates. Private session material and draft reports remain author-owned. Confirmed new events bind their own workspace without a commercial event allowance.

Fresh trial invitations

A verified first recipient invited through admin trial setup receives Source access on acceptance. No prepared event, report or commercial allowance is required. Ordinary teammate invitations do not grant this permission. Membership and current Source access remain required on every call; replaying an invitation cannot restore revoked access. The billing trial begins at organization creation and remains separate from Source permission and supplier funding.

Connected research and optional funding

Authorized Source users can confirm events, save evidence, submit candidates, develop assessments and save reports with their own connected agent. No commercial event or assessment allowance is required. Source access, organization ownership, evidence checks, request sizes and rate limits remain enforced.

Your host invokes Apollo, Clay, Bright Data or other available tools under your own permissions and charges. Argus does not install them, inherit their credentials or authorize purchases. Missing tools should lead to a useful alternative or a specific explanation of the evidence gap.

Capabilities and session reads expose connected_workspace and a separate funded_research summary within evaluation. Ducket-funded supplier requests still require approved funding. Existing purchased native research and prepared-report grants retain their own terms. Connected saving never resets those grants or authorizes sending.

The workflow previously called Preview is now the current workflow for all authorized users. Existing sessions retain their saved research and provenance. Read current workspace context before continuing; confirm an event brief before saving research against it.

Continuation and saved outreach

Connected skill version 1.4.0 adds company_report, outreach_save and outreach_read, with corresponding source_ MCP tools. company_context adds continuation by opportunity kind: task, report_ref, state, applicable, brief_version, session_id, qualification, inventory and readable report references. Tasks are research_first_report, continue_missing_work, advance_saved_report and reassess_changed_context. Completeness, qualification and inventory are separate. These reads execute no research or model call.

company_report takes run_id, account_key, kind and report_ref. The reference contains origin connected, native, supplemental or published; id; version; and content_sha256. It returns the full authorized document or native_report. Native reads use the member report projection and existing sample, product, task, section and evidence grants. They never open a paid report implicitly. Connected documents remain private to their author and organization unless an operator explicitly publishes a selected snapshot into that prepared workspace. Published reports contain attribution, dated source passages and the selected version, without private session access. A stale reference refuses with report_reference_changed.

outreach_save takes session_id, operation_id, expected_revision, brief_version, run_id, account_key, kind, report_ref, subject and body. Optional recipient_role, relationship and desired_outcome default to empty text. Subject is bounded to 300 characters, body to 16,000, recipient_role to 300, relationship and desired_outcome to 2,000 each. A nonempty subject and at least 20 body characters are required. The server requires an applicable completed current report and the same confirmed event context. New report and company-progress writes require a recognized domain match; two unresolved domains cannot establish company identity. Structural acceptance does not certify commercial quality.

A successful response contains outreach_draft and revision. The immutable draft records its ID/version, exact report_ref, brief/source bindings, subject/body, optional context, saved time, workspace URL, state draft and sent false. Identical content against the same report/context reuses its version and returns unchanged true. Substantive changes preserve earlier versions. Exact operation retries recover the original response; a historical retry can return applicable false. Reports also reuse an unchanged content version. Receipts remain stored and count toward logical storage.

outreach_read takes run_id, account_key and kind, with optional outreach_id, and returns outreach_drafts newest first. Signed-in members use GET /api/source-agent/account/companies/{run}/{account}/outreach?kind=sponsorship or exhibiting. Reads recheck author, organization, event/company and source-report access. Changed context marks history inapplicable; lost report access refuses with outreach_source_unavailable. Responses use Cache-Control no-store.

Writes preserve current Source permission, request/rate controls and evidence validation. No supplier call, native assessment slot, sent state or qualification change is created. Named refusals include report_reassessment_required, report_reference_changed, outreach_not_found, outreach_source_unavailable, outreach_integrity_failed. Missing or revoked Source access refuses before writes. Failed writes roll back. Saved reads remain subject to current identity and resource access.

Host guidance carries the event through natural follow-ups and saves supported output within an established sourcing/report task. Casual explanations are read-only unless saving is requested or belongs to that task. Suitable authorized host tools can supply evidence without forcing Argus-funded retrieval. Host availability alone grants no purchases, private access or sending. Full reports and drafts must also appear in the conversation; actual save outcomes are stated briefly.

Attributed external findings

Upload / source_upload retains external_unverified provenance. Optional external_source carries kind (public_company_source, organizer_document or structured_supplier_record), supplier, tool_name, original_retrieved_at as an ISO date or timestamp with timezone, entity, edition and quoted_material. Quotes must appear in the submitted text. This establishes supplied bytes only. Assertions remain unverified; private_crm and trusted flags refuse.

Evidence reads return external_source, attribution, ingested_at and verified_from_evidence_id where applicable. Verify with tool page, the exact original public URL and external_evidence_id. A successful guarded read creates a separate server_page capture and link. It never promotes the upload or certifies all its assertions. Redirect guards and existing entity, edition, quote and attribution checks apply.

Evidence and costs

Tool results contain bounded passages, source URLs, retrieval dates and opaque evidence handles. Original bytes remain server-side. A content hash establishes integrity. It does not establish truth. Search results are discovery evidence; an offering needs the company's own saved page. Costs identify their basis; unknown charges remain unknown. Declared client/model names are metadata rather than model attestation.

Evidence reads label older target-event editions with source_edition and historical. Citations may declare purpose as general, historical or current. Old rosters remain citable as history; current claims require the current edition. An edition_mismatch refuses history offered as current proof. Edition testimony uses the URL year, then the governing HTML H1, then title. A body year alone cannot establish edition. Ambiguous headings stay unknown; unknown does not prove current membership.

Ask for the complete source-linked report in your conversation as well as its saved Argus link and version. A link alone is insufficient. If the host has a message limit, ask it to complete clearly ordered parts. Commercial recommendations should connect the offering to audience buyers, name an intended business outcome, explain conditions and give the next qualification action. Host delivery is verified separately from document saving.

When a company already has a readable report, choose Read report or View report first. Continue with my agent lets you develop the saved work further. Native research permissions and allowance details are shown when they apply to a research or report-opening decision.

An open report stays visible while background reads refresh it. Transient refresh failures preserve its content and reading position; confirmed access refusal removes affected content. Native and connected report choices survive refresh and Back/Forward. Connected discovery cannot erase a separately authorized native report.

Reports include applicable on reads. A changed brief, qualification or supporting evidence makes the saved assessment need reassessment. Research state then reads needs_reassessment. The saved report stays available as history; requalification alone cannot reactivate it. Save an explicit research update and a new report. Legacy reports without a qualification binding need reassessment.

Retrying a successful report save with the original operation ID preserves the report and saved operation. An unchanged retry returns the original response. A stale retry uses the current report reader: applicable is false, research is needs_reassessment, mechanical_checks is incomplete and missing includes explicit_reassessment_required. The original success stays stored as history. No research is purchased. The response revision belongs to the original operation; resume before another edit.

Completion requires supported dates at their stated precision. A clearly completed opening in the current month can qualify without a fabricated day. Old, future and boundary-overlapping intervals remain unresolved. A negative needs an attributed adverse basis; this conservative check accepts explicit policies against buying sponsorships, with their quoted source in Against. Unknown findings and irrelevant quotes leave the report incomplete. Mechanical matching does not establish general semantic truth.

POST /api/source-agent/v1/operations
Authorization: Bearer <Source connection key>
Content-Type: application/json

{"session_id":"<saved session reference>","offset":0}

Refusals and recovery

HTTP uses 401 for missing/revoked credentials, 403 for missing access or scope, 404 for unavailable owned resources, 409 for stale state or conflicting operations, 413 for oversized requests, 422 for schema errors and 429 with Retry-After for operational rate protection. MCP reports named tool refusals with isError. Authentication precedes effects.

A pre-dispatch rate_limited HTTP 429 has retryable true. Honor Retry-After and stop further calls until the window ends. Uncertain supplier work stays non-retryable and requires reconciliation. The standalone client displays known refusal names while keeping arbitrary server text and credentials out of its errors; it never automatically retries.

Named errors include stale_brief, revision_conflict, operation_conflict, operation_uncertain, quote_not_on_page, research_not_found, empty_research, supplier_unconfigured and url_refused. A held investigation needs useful findings or writing. A valid research save returns research_id and in_progress; an incomplete report save returns missing work without a report_id. Resume before editing stale state. Recover lost answers through source_operations before another supplier request. Reuse the operation ID after disconnecting. An uncertain billed request must be reconciled; automatic replay is refused.

See setup, evidence and review, and the separate Argus API reference.