Skip to main content
Glama
Heliyos MCP server

Heliyos MCP server

Official
by heliyos-ai

List records

heliyos_records_list
Read-onlyIdempotent

Lists companies, people, deals, or custom object records in a Heliyos workspace, newest first, so you can browse and filter CRM data with search, field filters, and sort.

Instructions

Lists records of one object (companies, people, deals, or a custom object) in the Heliyos workspace, newest first. Use it to browse or filter records; use heliyos_records_lookup to find a record by name and heliyos_records_get for one record. Filter with search (free text) and filters (field conditions joined by match); order with sort. Returns a table of id, name and key fields plus structuredContent {records:[{id, object_type, name, fields}], next_cursor}. When next_cursor is present, call again with cursor set to it for the next page. Record ids feed heliyos_records_get, _update and _delete.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "object_type": "<object_type>"
    },
    "name": "heliyos_records_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoSort order. Omit for newest updated first. With a sort, next_cursor is a page cursor from this tool; pass it back unchanged.
limitNoRecords per page, 1 to 100. Default 20.
matchNo"all" (default): a record must meet every filter condition. "any": at least one condition.all
cursorNonext_cursor from the previous page, with the same limit. Omit for the first page.
searchNoPlain words matched across the record's text fields. Symbols such as + ( ) [ ] * ? can cause an error.
filtersNoField conditions, for example [{field:"stage", operator:"equals", value:"Won"}]. Joined by `match`.
schema_idNoObject schema id. Required when object_type is "custom"; the error lists the available ones.
object_typeYesWhich object: "company", "person", "deal", or "custom" (custom objects also need schema_id).
response_formatNo"concise" (default) returns the name and key fields; "detailed" returns every field and linked records.concise

Output Schema

NameRequiredDescriptionDefault
recordsYes
next_cursorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.1

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds behavior beyond that: newest-first default ordering, the exact pagination loop ("when next_cursor is present, call again with `cursor` set to it"), and the concise/detailed return distinction. It does not mention permissions or rate limits, which keeps it at 4 rather than 5.

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?

Four front-loaded sentences: purpose, sibling routing, parameter grouping, and return/pagination. Everything is dense and usable, though the return-shape sentence duplicates what the existing output schema already declares, which is the one place words could be trimmed.

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?

For a 9-parameter, nested-filter, paginated list tool with an output schema, the description covers purpose, alternatives, parameter grouping, pagination continuation, and downstream id usage. Nothing needed to call it correctly is missing, and return values being explained is a bonus rather than a gap since an output schema exists.

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% and every parameter, including the nested filter operators and the sort object, is documented in the schema itself. The description only restates the cross-parameter linkage ("filters (field conditions joined by `match`)") without adding syntax, value formats, or edge cases beyond what the schema already says. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

"Lists records of one object (companies, people, deals, or a custom object) in the Heliyos workspace, newest first" names a specific verb, the resource, the allowed object scopes, and the default ordering. It explicitly contrasts itself with heliyos_records_lookup (find by name) and heliyos_records_get (single record), so an agent can distinguish it from the nearest siblings without opening a 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?

The description states the browse/filter use case and then routes the agent away: use heliyos_records_lookup to find a record by name and heliyos_records_get for one record. It also gives the within-tool selection logic for `search` vs `filters` vs `sort`, and closes by noting that returned ids feed _get, _update and _delete, which tells the agent what to do next.

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