Skip to main content
Glama
ignytehq

plunk-mcp

Official
by ignytehq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

List contacts

plunk_list_contacts
Read-onlyIdempotent

Browse or search contacts with pagination, filters, and sorting to find contacts when you lack the exact address or want to see who is in the project.

Instructions

Purpose: Browse or search contacts, with cursor pagination, email search, subscription filter and sorting.

Not for: Resolving a batch of known addresses to contacts — plunk_lookup_contacts does that in one call instead of searching repeatedly.

Returns: A page of contacts with a cursor for the next page.

Use when: Exploring who is in the project, or finding a contact whose exact address you do not have.

Note: Prefer narrowing with search or subscribed over paging through everything. The subscribed filter and sorting require Plunk v0.12+.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dirNoSort direction (used with `sort=email|createdAt`).
pageNoLegacy page-based pagination. Prefer `cursor`.
sortNoColumn to sort by. `email` and `createdAt` are v0.12+; `alphabetical` and `latest` are legacy aliases.
limitNo
cursorNoCursor-based pagination token from a previous response.
searchNoCase-insensitive substring match on email.
subscribedNoFilter by subscription state. Omit for both.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv2.0.0
    • addedInput schema / $schema
      Added value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / limit / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / limit / minimum
      Added value: +-9007199254740991
    • addedInput schema / properties / page / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / page / minimum
      Added value: +-9007199254740991
  2. First observedv1.2.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so safety is covered. The description adds genuinely useful behavior beyond that: cursor-based paging, that a next-page cursor is returned, and a version gate ('subscribed filter and sorting require Plunk v0.12+'). It stops short of rich context like rate limits or page-size behavior.

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?

Bold section labels (Purpose/Not for/Returns/Use when/Note) make it scannable and front-load the key routing fact. Slightly heavy scaffolding for the amount of content, but every line earns its place and there is no filler.

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

Completeness5/5

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

The tool has no output schema, and the description compensates by stating what is returned (a page of contacts plus a cursor for the next page). Combined with the routing guidance and version notes, an agent has everything needed to call it correctly.

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 86%, so the schema already documents most parameters and the baseline would be 3. The description nonetheless adds cross-cutting parameter meaning: the preferred pagination mode (search/subscribed over paging), the fact that subscription state is a filter, and the version prerequisite for the subscribed filter and sorting. That is real value above the schema's per-field text.

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

Purpose5/5

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

States a specific verb and resource ('browse or search contacts') and immediately names the sibling it is not for (plunk_lookup_contacts). An agent can distinguish the exploratory list/search path from the batch-resolution path without opening either schema.

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?

Explicit 'Not for' routing to plunk_lookup_contacts, an explicit 'Use when' for exploration and looking up unknown addresses, plus a 'Prefer narrowing with search or subscribed over paging' directive. When-to-use, when-not, and the alternative are all stated.

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