Skip to main content
Glama

Search records

search_records
Read-only

List/filter any object; built-ins use typed search filters. Returns records, count, object_type, next_cursor, has_more and search_coverage. Follow every page for exhaustive answers. Unsupported filters are ignored and echoed in ignored_filters with coverage status unsupported_query: these rows do not answer the question; fix inputs before claiming matches or none. Unknown types return valid types. Most objects sort newest first; tasks by due ascending, undated last. Opportunity rows include account_last_inbound_at/account_last_touch_at for reply-recency questions. Task projection:'actions' includes sequence steps, deduplicates reminders, and returns exact counts plus paged rows. Write using taskId/enrollmentId, never projection ids. Nothing is sent.

When to use: A plain list — open tasks, deals in a stage, contacts at an account — before run_report; email matches carry a highlighted snippet.

Example: Find the emails to sally@acme.com.

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": "search_records"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoPage size, 1–100 (default 20). Out-of-range values are clamped.
queryNoFree-text names on account, contact, opportunity, lead, task, touch and meeting; for touch/activity also email subject/summary, stored email body content, and participant addresses. Object types without free-text search ignore it (noted in the result).
cursorNoOpaque keyset cursor: pass the previous page's next_cursor to fetch the next page; omit for the first page (a stale or invalid cursor restarts from page one).
filtersNoField key → exact scalar (string/number/boolean); relationships use target ids. Built-in typed search keys apply. Example for opportunity: {stage:'proposal',open_only:true} or {type:'renewal',open_only:true}. Non-scalars and unsupported keys are ignored with a note.
projectionNoRead-only unified Actions queue for object_type task, including sequence steps. Filters: scope mine/team/all (assignment, not book); bucket due/upcoming/paused/completed/all; channel email/call/linkedin/other; source task/sequence; sequence or owner UUID; day YYYY-MM-DD; time_zone IANA; timed_only.
object_typeYesObject key to list — a built-in (account, contact, opportunity, task, touch, meeting, attachment, report…), a custom object's key, or an opportunity type key such as renewal (auto-routed).

Output Schema

NameRequiredDescriptionDefault
noteNo
countNo
totalNo
countsNo
resultNo
recordsNo
has_moreNo
projectionNo
next_cursorNo
object_typeNo
ignored_filtersNo
search_coverageNo
cursor_restartedNo
custom_field_definitionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / object_type / description
      Previous value: -"Object key to list — a built-in (account, contact, opportunity, task, touch, meeting, report…), a custom object's key, or an opportunity type key such as renewal (auto-routed)."New value: +"Object key to list — a built-in (account, contact, opportunity, task, touch, meeting, attachment, report…), a custom object's key, or an opportunity type key such as renewal (auto-routed)."
  2. Changed3 schema fields changed
    • changedInput schema / properties / filters / description
      Previous value: -"Field key → exact scalar value (string / number / boolean). Non-scalar values can't be matched and are ignored with a note."New value: +"Field key → exact scalar (string/number/boolean); relationships use target ids. Built-in typed search keys apply. Example for opportunity: {stage:'proposal',open_only:true} or {type:'renewal',open_only:true}. Non-scalars and unsupported keys are ignored with a note."
    • changedInput schema / properties / projection / description
      Previous value: -"Read-only unified Actions queue, for object_type task."New value: +"Read-only unified Actions queue for object_type task, including sequence steps. Filters: scope mine/team/all (assignment, not book); bucket due/upcoming/paused/completed/all; channel email/call/linkedin/other; source task/sequence; sequence or owner UUID; day YYYY-MM-DD; time_zone IANA; timed_only."
    • changedInput schema / properties / query / description
      Previous value: -"Free-text search. Matches names + (for touch/activity) email subject/summary, stored email body content, and participant addresses. Object types without free-text search ignore it (noted in the result)."New value: +"Free-text names on account, contact, opportunity, lead, task, touch and meeting; for touch/activity also email subject/summary, stored email body content, and participant addresses. Object types without free-text search ignore it (noted in the result)."
  3. Changed1 schema field changed
    • addedOutput schema / properties / cursor_restarted
      Added value: +{
      +  "type": "boolean"
      +}
  4. Changed2 schema fields changed
    • removedInput schema / properties / limit / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]
    • addedInput schema / properties / limit / type
      Added value: +[
      +  "number",
      +  "string"
      +]
  5. Changed1 schema field changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
  6. Changed17 schema fields changed
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / additionalProperties
      Removed value: -{}
    • removedOutput schema / properties / counts / additionalProperties
      Removed value: -{}
    • removedOutput schema / properties / counts / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / custom_field_definitions / items / additionalProperties
      Removed value: -{}
    • removedOutput schema / properties / custom_field_definitions / items / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / next_cursor / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / next_cursor / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / records / items / additionalProperties
      Removed value: -{}
    • removedOutput schema / properties / records / items / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / result / additionalProperties
      Removed value: -{}
    • removedOutput schema / properties / result / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / search_coverage / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / search_coverage / properties / has_more / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / search_coverage / properties / has_more / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • removedOutput schema / properties / search_coverage / properties / next_cursor / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / search_coverage / properties / next_cursor / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  7. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare read-only/non-destructive/non-idempotent, yet the description adds substantial behavioral context beyond them: pagination must be followed exhaustively, unsupported filters are ignored and echoed in ignored_filters with unsupported_query coverage status, unknown object types return valid types, per-object sort orders, opportunity reply-recency fields, and the projection 'actions' semantics with reminder deduplication. 'Nothing is sent' also reassures on side effects.

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?

Front-loaded with purpose, then behavior, then a labeled 'When to use' block and example — a sensible ordering. It is dense and several clauses are run-on (filter/coverage/sort rules crammed into one paragraph), so some information could be tightened, but almost every sentence carries operational content.

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?

Covers paging, coverage failure modes, sort behavior, and projection specifics for a complex 6-parameter tool with nested filters. It spends some words enumerating return fields (records, count, next_cursor, has_more, search_coverage) that the output schema already provides, which is mild redundancy rather than a gap.

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 nonetheless adds interpretive meaning — that projection is a read-only Actions queue for object_type=task, that sequence steps appear and reminders are deduplicated, and that projection ids are not writable identifiers. That is genuine value beyond the schema, though the per-key filter detail is partly restated in the schema.

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?

Opens with a specific verb and resource ('List/filter any object') and immediately narrows scope ('built-ins use typed search filters'). It contrasts itself with run_report and enumerates concrete list examples (open tasks, deals in a stage, contacts at an account), so an agent can distinguish it from siblings without reading the 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?

A dedicated 'When to use' block names the alternative (run_report) and the condition that selects it ('a plain list ... before run_report'), plus a worked example. It also states a hard stop condition — unsupported filters mean 'fix inputs before claiming matches or none' — and a write-path caveat ('Write using taskId/enrollmentId, never projection ids').

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.

Resources