Groundbase

List contacts

contacts_list

Read-onlyIdempotent

Search and filter contacts (tag, status, company, unsubscribed, sort), or id for one in full (tags, addresses, custom fields, recent activity). deleted: to restore. duplicates: to merge.

Input Schema

Name	Required	Description
`id`	No	One contact by id.
`tag`	No	Only contacts with this tag (name or id).
`sort`	No	recent = last contacted. Default name.
`limit`	No	Default 50.
`offset`	No
`search`	No	Matches name, email, phone.
`status`	No	Status name or id, or none.
`deleted`	No	List recently deleted contacts instead.
`companyId`	No	Only contacts at this company.
`duplicates`	No	Groups sharing an email or phone instead.
`unsubscribed`	No	Opted out of any / email / sms, or none.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 19, 2026

changedInput schema / properties / duplicates / description

Previous value: -"List groups of live contacts sharing an email or phone instead."New value: +"Groups sharing an email or phone instead."

changedInput schema / properties / id / description

Previous value: -"Contact id. Returns that one contact; other filters ignored."New value: +"One contact by id."

addedInput schema / properties / status

Added value: +{
+  "description": "Status name or id, or none.",
+  "type": "string"
+}

changedInput schema / properties / unsubscribed / description

Previous value: -"Opted out of any channel / email / texts, or none (for an audience)."New value: +"Opted out of any / email / sms, or none."

Changed6 schema fields changedOct 9, 2026

addedInput schema / properties / companyId

Added value: +{
+  "description": "Only contacts at this company.",
+  "type": "string"
+}

addedInput schema / properties / deleted

Added value: +{
+  "description": "List recently deleted contacts instead.",
+  "type": "boolean"
+}

addedInput schema / properties / duplicates

Added value: +{
+  "description": "List groups of live contacts sharing an email or phone instead.",
+  "type": "boolean"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "recent = last contacted. Default name.",
+  "enum": [
+    "name",
+    "created",
+    "updated",
+    "recent"
+  ],
+  "type": "string"
+}

addedInput schema / properties / tag

Added value: +{
+  "description": "Only contacts with this tag (name or id).",
+  "type": "string"
+}

addedInput schema / properties / unsubscribed

Added value: +{
+  "description": "Opted out of any channel / email / texts, or none (for an audience).",
+  "enum": [
+    "any",
+    "email",
+    "sms",
+    "none"
+  ],
+  "type": "string"
+}

Changed4 schema fields changedOct 1, 2026

addedInput schema / properties / id

Added value: +{
+  "description": "Contact id. Returns that one contact; other filters ignored.",
+  "type": "string"
+}

changedInput schema / properties / limit / description

Previous value: -"Max results (1-1000, default 50)."New value: +"Default 50."

removedInput schema / properties / offset / description
```
Removed value: -"Pagination offset, default 0."
```

changedInput schema / properties / search / description

Previous value: -"Free-text search across name, email, phone."New value: +"Matches name, email, phone."

First observedSep 23, 2026

TDQS

A4.1/5.0

Behavior4/5

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

The annotations already declare read-only, idempotent, non-destructive behavior, so the description only needs to add nuance. It usefully explains that `id` returns full details including tags, addresses, custom fields, and recent activity, and that `deleted`/`duplicates` serve restore/merge workflows.

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

Conciseness5/5

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

The description is extremely compact and front-loaded, covering the main search/filter use, the single-contact mode, and the two special result modes in one dense but readable passage. There is no filler.

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 an 11-parameter, read-only listing tool with no output schema, the description covers the important modes and clarifies what `id` returns. It omits pagination defaults and return shape details, but those are largely handled by the schema and annotations.

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 91%, so the schema already documents most parameters. The description adds meaning beyond the schema by grouping the filter dimensions and clarifying that `id` returns an enriched contact view and that `deleted` and `duplicates` change the result mode.

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 clear verb and resource: search/filter contacts, with special modes for a single `id`, `deleted`, and `duplicates`. It does not explicitly name or contrast with the sibling `contacts_manage`, but the listing/read scope is clear from the wording.

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

Usage Guidelines4/5

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

It gives concrete usage conditions: use `id` for one full contact, `deleted` to restore, and `duplicates` to merge. It does not explicitly state when not to use this tool or name an alternative sibling, but the mode guidance is strong.

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

All Groundbase tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?