MCP

MCP Tools Reference

Review available MCP tools, data models, request inputs, filters, output shapes, limits, and tool-selection guidance.

Review the MCP tools an AI client can use, what each tool should be used for, required inputs, optional filters, response shapes, and reliability guidance.

Kommon Poll MCP tools are designed for AI-workflow users. The model should use them when the user asks about monitored conversation data, saved searches, mentions, sentiment, trends, competitors, campaigns, reports, or customer feedback.

AI clients may display localized or simplified tool labels, but the Kommon Poll MCP capability set maps to the tools and scopes below.

1. Tool Selection Pattern

Most workflows follow this sequence:

  1. List saved searches when the user has not specified the exact project.
  2. Choose the saved search that matches the user's request.
  3. Retrieve overview analytics for quantitative claims.
  4. Retrieve mentions for examples, evidence, root-cause investigation, or qualitative analysis.
  5. State the date range, filters, saved search, and limitations in the answer.

The AI should not invent saved-search identifiers or assume access to a project that is not returned by the tools.

2. Available Capabilities

Tool or capability Scope Access What it does When the AI should call it Example user request
List saved searches kommonpoll:saved-searches:read Read Discovers projects or searches the authenticated user can access. When the user asks what is available, or when the requested project is ambiguous. "What Kommon Poll projects can you access?"
Get saved-search overview kommonpoll:overview:read Read Returns aggregate analytics for one authorized saved search, optionally filtered. Before making quantitative claims about volume, sentiment, reach, interactions, influence, platforms, topics, or trends. "Summarize the last 7 days for our brand search and compare sentiment by platform."
Get saved-search mentions kommonpoll:mentions:read Read Returns paginated individual mentions for qualitative analysis, examples, evidence, or top-post inspection. When the user asks for examples, complaints, top posts, influential mentions, source links, or evidence. "Find the most influential negative mentions from the last 30 days and explain the recurring complaints."
Create saved search kommonpoll:saved-searches:create Write Creates a saved social-listening search in an approved developer or admin workflow. Only when the client is explicitly authorized for write access and the user asks to create a search. "Create a saved search for this campaign query."
Update saved search kommonpoll:saved-searches:update Write Updates the title, Boolean keyword, or description of an existing saved search in an approved developer or admin workflow. Only when the client is explicitly authorized for write access and the user confirms the exact saved search and change. "Rename this saved search and update its description."

Most customer-facing AI analysis workflows should request only the three read scopes. Write-capable tools are for controlled workflows and should be disabled unless the client is intended to manage saved-search setup.

3. Saved Searches Data Model

Saved-search listing output should help the AI select the correct project.

Typical fields can include:

  • Saved-search name or title.
  • Stable saved-search identifier, exposed to MCP clients as saved_search_id.
  • Team or workspace context resolved server-side.
  • Search type or project type where available.
  • Boolean keyword query where available to the authorized client.
  • Description or topics where available.
  • Created or updated timestamps where available.

The AI should use saved-search names for user-facing explanations and stable identifiers for subsequent tool calls.

4. Overview Analytics Data Model

Overview output can include:

  • Total matching mentions.
  • Platform and source breakdowns.
  • Sentiment and polarity statistics.
  • Subjectivity statistics.
  • Reach, interactions, views, likes, comments, and shares.
  • Influence score aggregates.
  • Unique authors and domains.
  • Topic, subtopic, keyword, hashtag, intent, entity, and CTA breakdowns.
  • Date and time buckets for trend analysis.
  • Language, geography, demographics, and audience attributes where available.

Use overview tools for aggregate claims. Do not use a small mentions page as proof of the entire dataset unless the workflow explicitly supports sampling.

5. Mentions Data Model

Mention output can include:

  • Mention ID.
  • Source URL.
  • Platform and domain.
  • Published, collected, ingested, and updated timestamps where available.
  • Author name or handle where available.
  • Mention text, clean text, title, key phrases, language, and post type.
  • Likes, comments, shares, views, reach, interactions, and influence fields where available.
  • Sentiment, polarity, and subjectivity.
  • Entities such as people, companies, products, locations, and events.
  • Highlights for matched terms.
  • Context arrays or related classification fields where available.

Not every platform exposes every field. Missing values should not automatically be treated as zero.

6. Supported Filters

Where supported by the tool, filters can include:

  • Date range and timezone.
  • Time of day.
  • Platform or source.
  • Country, location, language, age, gender, education, income, nationality, and business-author flags.
  • Included or excluded authors.
  • Included or excluded hashtags.
  • Included or excluded domains.
  • Tags, priority, subtopics, intents, and action/content classifications.
  • Sentiment, subjectivity, reach, interaction, and influence ranges.
  • Collection and ingestion dates.
  • Optional plain-text phrase used to narrow the authorized saved search.

The AI should state which filters were applied. If the user asks for a filter the tool does not expose, the AI should say so and offer the closest supported workflow.

7. Output Limits And Pagination

Mention tools may return paginated results.

For evidence-heavy workflows:

  • Retrieve a focused page first.
  • Sort by recency, engagement, reach, or influence depending on the goal.
  • Request additional pages only when needed.
  • Avoid claiming complete coverage from a small page of mentions.
  • State whether examples are representative, top-ranked, or sampled.

8. Example Prompts

List the Kommon Poll saved searches you can access and group them by team if that information is available.
For the "Brand Monitoring" saved search, summarize the last 7 days by volume, sentiment, reach, interactions, influence, platforms, and top themes.
Find the 20 most influential negative mentions from the last 30 days. Group them by recurring complaint and include source links.
Compare Facebook, Instagram, and news mentions for the campaign search from 1 August 2026 to 31 August 2026. State filters and limitations.