Skip to main content
Glama

List polls

list_polls
Read-onlyIdempotent

Every public poll, latest run first, filtered and sorted as the directory at /polls is: by topic (a topic's slug), status, model, lab and search, sorted by latest run, newest, most answers or ending soon. With a key that has the read scope, mine=true lists your own polls instead (a test key lists test polls only; the filters apply to public polls). Use updated_since to fetch only polls that changed, then get_results for each. (GET /api/v1/polls)

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_polls"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoPublic polls: only those whose title, description, first question or topics contain every word given.
labNoPublic polls: only those asking a model from this lab, such as Anthropic.
mineNotrue: your own polls (needs a key with read). Default: public polls.
sortNoPublic polls: latest run first (the default), newest published, most answers, or soonest end date (polls with none last).latest
limitNoItems per page, 1 to 100.
modelNoPublic polls: only those asking this model, by its display name.
topicNoPublic polls: only those with this topic, by its slug (as in /polls/topics/{slug}).
cursorNonext_cursor from the previous page, unchanged.
statusNoPublic polls: running (on a schedule), stopped (ended, paused, or run once by hand), or all (the default).all
updated_sinceNoOnly polls whose last run or edit is after this moment.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavioral context the annotations cannot: the ownership switch behind mine, the test-key restriction, and the caveat that filters only affect public polls. It does not describe pagination behavior, though the cursor parameter covers that mechanically.

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?

Two dense sentences, front-loaded with scope and ordering before the conditional mine behavior. The phrase 'filtered and sorted as the directory at /polls is' is slightly gawky but does useful work by anchoring to a known UI behavior.

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

Completeness4/5

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

For a 10-parameter, zero-required list tool with full schema coverage and a complete annotation set, it supplies the missing behavioral layer (ownership, test keys, filter scoping, incremental sync). Nothing essential for a correct call is absent, though pagination workflow is implicit rather than stated.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that the filter parameters (topic, status, model, lab, search, sort) apply only to public polls and are bypassed when mine=true, an interaction the schema does not state. The sort vocabulary and date filtering it repeats are already fully documented in the schema.

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?

Opens with a specific verb+resource (list every public poll) plus default ordering, which is far more than a restatement of the name. It hints at the follow-up tool (get_results) but never distinguishes itself from get_poll for a single-poll lookup, so sibling differentiation is only partial.

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

Usage Guidelines5/5

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

Gives explicit conditional routing: mine=true with a read-scoped key lists your own polls, a test key lists test polls only, and filters apply to public polls. It also names the incremental workflow (use updated_since to fetch only changed polls, then get_results for each), leaving nothing to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.