MCP / API REFERENCE

Tools & arguments

Complete arguments, result structures, and invocation rules. After authorization, use the tool names and schemas actually exposed by the client.

MCP tool reference

These are MCP tool arguments, not REST form fields or OAuth parameters. The client invokes tools through tools/call and manages tokens. Examples use synthetic data and fictional job IDs; do not create a report merely to test connection.

create_report

Purpose: asynchronously create a new report in the authorized workspace. OAuth scope: reports.write. Each call creates a new job.

Argument	Type	Required	Default	Meaning
outline	string	Yes	—	Complete Markdown outline with verified findings, metrics and aggregated chart data; nonempty, at most 1,000,000 UTF-8 bytes.
locale	string	No	zh-CN	Report language, for example zh-CN or en. The current interface does not restrict this string to an enum.

outline must follow the complete reference: # main title, > subtitle, meta information, ## page headings and page layouts. The service extracts the report name from the first nonempty # title (at most 300 UTF-8 bytes) and requires at least one nonempty ## page. Set meta.pages to the actual page count. Do not pass a JSON object or file path as outline.

Do not send title, outline_markdown, workspace_id, idempotency_key, or other extra arguments. The title comes from outline and the workspace comes from OAuth authorization.

Complete argument example (synthetic data)

Expand complete JSON example

{
  "outline": "# Agency Client Performance Review\n\n> Synthetic demonstration data for July–September 2026; not a real client report.\n\n<!-- meta\ngoal: Review campaign efficiency and agree on next month's priorities\nskill: agency-client-review\nstyle: default\nlang: business\npages: 3\naudience: Client marketing lead\ndate_range: 2026-07-01 to 2026-09-30\ngenerated: 2026-10-05\n-->\n\n---\n\n## Data overview\n`layout: KPI Ledger`\n`layout_intent: Summarize verified quarterly performance before reviewing definitions.`\n`layout_slots: kpi-summary`\n\n- [slot: kpi-summary] Quarterly performance [smart_layout]\n  | Metric | Current value | Description |\n  |---|---|---|\n  | Ad spend | USD 30,000 | Total July–September campaign spend |\n  | Attributed revenue | USD 105,000 | Revenue attributed using the demo's fixed 7-day click window |\n  | ROAS | 3.50x | USD 105,000 / USD 30,000; excludes agency fees |\n  Evidence: Monthly ROAS increased from 3.00x in July to 4.00x in September.\n  Attribution: These aggregates show an efficiency trend, but do not establish its cause.\n  Recommendation: Review channel and campaign breakdowns before reallocating budget.\n\n---\n\n## Data definitions\n`layout: Specification Sheet`\n`layout_intent: Define the source, attribution window and calculation scope.`\n`layout_slots: spec-body`\n\n- [slot: spec-body] Measurement scope [smart_layout]\n  | Definition | Value |\n  |---|---|\n  | Source | Synthetic monthly campaign aggregates for this example |\n  | Scope | July–September 2026; all amounts in USD |\n  | Spend by month | July 10,000; August 10,000; September 10,000 |\n  | Revenue by month | July 30,000; August 35,000; September 40,000 |\n  | ROAS definition | Attributed revenue / ad spend; fixed 7-day click window |\n  Footnote: Agency fees, organic revenue and refunds are excluded. No causal or incremental-lift conclusion can be made from these aggregates.\n\n---\n\n## Validate the efficiency trend before increasing investment\n`layout: Closing Statement`\n`layout_intent: Turn the measured trend into specific next steps without asserting causality.`\n`layout_slots: takeaways`\n\n- [slot: takeaways] Findings and next steps [smart_layout]\n  Findings:\n  01. Quarterly ROAS was 3.50x on USD 30,000 of spend.\n  02. Monthly attributed revenue rose from USD 30,000 to USD 40,000 while spend stayed constant.\n  03. The aggregate data cannot isolate the drivers or confirm incremental revenue.\n  Actions:\n  P1. Marketing lead: validate attribution and refund handling before the next review.\n  P2. Agency analyst: compare channels and campaigns using consistent attribution definitions.\n  P3. Account lead: agree on a controlled budget test after validating the breakdown.\n  Goal: Confirm a repeatable efficiency improvement before scaling spend.\n",
  "locale": "en"
}

Successful creation data

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "status": "running",
  "report_url": "https://www.exceldashboard.ai/report/preview/11111111-1111-4111-8111-111111111111?b=report",
  "poll_after_seconds": 15
}

Result field	Type	Meaning
job_id	string	New job ID. Save it for subsequent status queries.
status	string	running at successful submission; this does not prove completion.
report_url	string	Public read-only preview URL. Immediately show the exact returned link.
poll_after_seconds	integer	Recommended polling interval, currently 15 seconds.

get_report

Purpose: read a job created by the current user in the authorized workspace. OAuth scope: reports.read; this tool does not modify reports.

Argument	Type	Required	Meaning
job_id	string	Yes	The job ID returned by create_report, not report_id, a share ID or a full URL. No default.

{
  "job_id": "11111111-1111-4111-8111-111111111111"
}

Complete running result example

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "operation": "create",
  "status": "running",
  "stage": "generating",
  "completed_pages": 1,
  "pages_started": 2,
  "total_pages": 3,
  "report_id": null,
  "report_url": "https://www.exceldashboard.ai/report/preview/11111111-1111-4111-8111-111111111111?b=report",
  "share_url": null,
  "poll_after_seconds": 15,
  "error_code": null,
  "error_message": null
}

Result field	Type	Meaning
job_id	string	The queried job ID.
operation	string	create for jobs created by this connector.
status	string	running: keep tracking; completed: generation finished; failed: stop and explain the failure.
stage	string	Backend stage label; do not assume a fixed stage enum or infer a percentage from it.
completed_pages	integer	Completed page count reported by the backend.
pages_started	integer	Started progress count while generating; not completed pages, and can be 0 after the job ends.
total_pages	integer	Total pages counted from the outline’s ## headings.
report_id	string or null	Report resource ID, possibly null while generating; never substitute it for get_report.job_id.
report_url	string	Report preview entry point, also returned while running; its existence does not prove completion.
share_url	string or null	Underlying public share URL after completion, possibly null. Prefer report_url in user replies.
poll_after_seconds	integer or null	Currently 15 seconds while running; null when the job ends.
error_code	string or null	Job error or share-preparation warning code; null when absent.
error_message	string or null	Associated error or warning description.

Stop polling immediately on completed or failed. Successful generation can still carry a share-preparation warning; explain it. After a creation timeout, query the original job when its ID is known. Without an ID, submission is uncertain: ask before recreating.

MCP result envelope and errors

The examples above are business result data. Actual successful MCP tool results include structuredContent and content[0].text (the JSON-encoded business data), with isError false. Prefer the client’s structured result and do not rely only on HTTP status.

{
  "isError": true,
  "structuredContent": {
    "error_code": "INVALID_ARGUMENT",
    "message": "Invalid create_report arguments"
  },
  "content": [
    {
      "type": "text",
      "text": "INVALID_ARGUMENT: Invalid create_report arguments"
    }
  ]
}

Failure	Meaning and recovery
INVALID_ARGUMENT	Invalid arguments or outline; correct them using the actual error message.
NOT_FOUND	Job absent or inaccessible to the current user/workspace; check the original job ID and authorization.
SERVER_ERROR	Service could not create or read a job; do not automatically recreate an uncertain submission.
HTTP 401	Missing or invalid token; reauthorize through the client.
HTTP 403	Insufficient scope; follow WWW-Authenticate and authorize the required scope.
status: failed	The status query succeeded but generation failed; read error_code/error_message and stop polling.