Skip to main content
Glama
thenavidm

Beehiiv MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

List polls

list_polls
Read-onlyIdempotent

Fetches polls for a specified publication, with pagination, sorting by creation date or name, and filtering by post. Optionally expand to include stats or responses.

Instructions

List polls. Reads account data. OAuth integrations require polls:read.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNo**Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned.
limitNoA limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
cursorNo**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination.
expandNoOptionally expand the response to include additional data. `stats` - Returns aggregate vote counts per choice and total completions. `poll_responses` - Returns up to 10 most recent subscriber responses. Use /polls/{pollId}/responses for paginated access to all responses. `trivia_answer` - Returns the correct answer for trivia-type polls.
accountNoNamed private account from BEEHIIV_ACCOUNTS. Defaults to BEEHIIV_DEFAULT_ACCOUNT or the first configured account.
post_idNoFilter to only return polls that were embedded in the specified post. Accepts a prefixed post ID (e.g. `post_abc123`).
order_byNoThe field that the results are sorted by. Defaults to created. `created` - The time the poll was created. `name` - The name of the poll.created
all_pagesNoRead successive cursor pages, bounded by max_items (default 1000).
directionNoThe direction that the results are sorted in. Defaults to asc. `asc` - Ascending, sorts from smallest to largest. `desc` - Descending, sorts from largest to smallest.asc
max_itemsNoMaximum records when all_pages=true. Returns continuation cursor and truncation.
publication_idYesThe prefixed ID of the publication object

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered by structured data. The description adds the OAuth scope requirement (polls:read), which is genuine value beyond annotations, but 'Reads account data' largely restates readOnlyHint and nothing is said about result volume or pagination behavior beyond what the schema already documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with essentially no wasted words; the purpose and access constraint come first. The opening 'List polls' duplicates the tool name and title, which is a minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter read tool with full schema coverage, rich annotations, and no output schema, the structured fields carry most of the burden. The description is minimally viable but omits any routing versus sibling poll tools, leaving a real gap for an agent choosing among them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 11 parameters, including pagination, expand, ordering, and filtering semantics, so the schema does the heavy lifting. The description adds no parameter-level meaning, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('List polls'), so an agent immediately knows it is a retrieval operation. However, it offers no differentiation from close siblings such as get_poll or polls_list_responses, so it is clear but not distinguishing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_poll (single poll) or polls_list_responses (responses to a poll). The only contextual statement is an OAuth scope note, which is an access requirement rather than a usage guideline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools