Tool Reference
The 37 VOC Insight MCP tools, business meanings, and chargeable actions.
Tool Usage Principles
In customer-facing conversations, use business language such as “view brand list”, “refresh data”, or “find negative posts”. Tool IDs are mainly for implementation, QA, and troubleshooting.
Collection tools return a jobId. After that, use get_refresh_progress until the job reaches completed before reading data. Do not repeatedly create or refresh while collection is running.
AI deep follow-up has a sync and an async path. The sync report_follow_up_analysis returns the report directly (30–100s). If the client or link has a hard response timeout (e.g. a Cloudflare ~60s edge gateway), start the async report_follow_up_analysis_async instead, then poll wait_for_analysis until done and take the report. Both paths yield identical results and billing (600 points on success).
When the user asks who customers are or why they buy or do not buy, read the free get_persona_voc overview first, then drill into only the needed availableSections with get_persona_section. Call async generate_persona_voc only when no persona report exists or the user explicitly requests regeneration and confirms the cost; check it with get_persona_generation_progress and do not repeat an active generation.
37-Tool Quick Reference
| Group | Tool ID | Business Meaning | Billing Type |
|---|---|---|---|
| Context and rules | social_capabilities | Capability introspection | Free |
| Context and rules | get_context | Account, billingMode, brands, supported platforms | Free |
| Context and rules | get_billing_rules | Point billing rules | Free |
| Context and rules | suggest_next_actions | Recommended next actions | Free |
| Context and rules | explain_error | Error explanation and next action | Free |
| Knowledge space | prepare_space | Collection plan and cost estimate | Free |
| Knowledge space | create_space | Create knowledge space and first collection | Collection pricing |
| Brand management | list_brands | Existing brands/spaces | Free |
| Brand management | get_brand | Brand configuration and data status | Free |
| Brand management | prepare_brand_onboarding | Full brand onboarding suggestions | Free |
| Brand management | setup_brand | Full brand onboarding | Collection pricing |
| Brand management | update_brand | Update brand configuration | Free |
| Collection | diagnose_brand | Data readiness check | Free |
| Collection | refresh_brand | Refresh existing brand data | Collection pricing |
| Collection | get_refresh_progress | Collection progress | Free |
| Collection | wait_for_refresh | Short wait for collection completion | Free |
| Analysis | get_analysis_progress | Async AI deep follow-up progress | Billed on completion |
| Analysis | wait_for_analysis | Short wait for async AI deep follow-up | Billed on completion |
| Data reading | get_brand_metrics | Core metrics and platform distribution | Free |
| Data reading | search_brand_posts | Search posts by filters | Free |
| Data reading | find_posts_about | Semantic post search | Free |
| Data reading | get_brand_sentiment | Sentiment distribution and drivers | Free |
| Data reading | get_voice_share | Voice share | Free |
| Data reading | compare_competitors | Multi-dimensional competitor comparison | Free |
| Data reading | get_risk_alerts | Risk alerts | Free |
| Report / Analysis | get_social_voc_report_kit | Free social VOC report kit (default first choice; assemble HTML locally) | Free |
| Report / Analysis | report_follow_up_analysis | AI deep follow-up (sync, returns the report directly) | AI deep follow-up pricing |
| Report / Analysis | report_follow_up_analysis_async | AI deep follow-up (async start, survives edge timeouts; poll with wait_for_analysis) | Free to start, billed on completion |
| Report / Analysis | get_brand_summary | Quick brand summary | Free |
| Persona | get_persona_voc | Read persona overview | Free |
| Persona | get_persona_section | Read persona modules and paginated data on demand | Free |
| Persona | generate_persona_voc | Generate or regenerate personas asynchronously | 99 credits = 59,400 points |
| Persona | get_persona_generation_progress | Check persona generation progress | Free |
| Persona | list_persona_questions | Read starter questions for each persona | Free |
| Persona | ask_persona | Ask one persona or use analyst mode | 1 credit = 600 points/call |
| Persona | ask_all_personas | Ask all personas the same question | 1 credit = 600 points/request, not per persona |
| Persona | get_persona_interview_summary | Summarize a first-person persona interview | Free |
Billed Tools
| Tool | Billing Rule |
|---|---|
create_space | Creates a knowledge space and starts first collection; billed by estimated points after collection is accepted |
setup_brand | Full brand onboarding and collection; billed by estimated points after collection is accepted |
refresh_brand | Refreshes an existing brand; billed by estimated points after collection is accepted |
report_follow_up_analysis | AI deep follow-up query (sync); billed at 600 points after a successful reply |
report_follow_up_analysis_async + wait_for_analysis / get_analysis_progress | AI deep follow-up query (async); free to start, billed 600 points the moment a poll returns done. Repeated polls of the same job are never double-charged |
generate_persona_voc | Async persona generation; billed 99 credits (59,400 points) after acceptance. Check the overview/progress first and never duplicate an active run |
ask_persona | Persona interview or analyst answer; 1 credit (600 points) per successful call |
ask_all_personas | One broadcast question costs 1 credit (600 points), regardless of persona count |
See VOC Insight MCP Pricing for the collection point formula.