Mark

Search Posts

search_posts

Read-onlyIdempotent

Finds posts by status (in_review is the review queue), channel, scheduled time range, angle, pillar, text, or website CMS delivery state. Returns each post's current rev, updatedAt, mediaCount (assets, a website cover and images from the CMS; 0 means no media, so finding posts without an image needs no get_post per post) and, for website posts, the buyer questions it answers (buyerQuestions). A refresh of a live website page Mark published carries refresh: { text, pageUrl }, the reason Mark queued it for review; refresh is null on every other post. An approved social post moves to scheduled within seconds while Mark hands it to the publisher; handoff says handing_off then, or stuck with the reason and fix when it can't go (no scheduled time, no connected account, or no progress 5 minutes after approval). An approved LinkedIn Article carries handoff publish_by_hand before its scheduled time and publish_now from it on, each with the reason (a person publishes it on LinkedIn). handoff is null on every other post. status: approved still matches handing-off, stuck, publish_by_hand and publish_now posts. rev is the frozen revision: it stays 0 on drafts and only advances when the post is submitted (or frozen). updatedAt confirms a draft save. from and to filter by scheduled time, not created or updated. Each accepts YYYY-MM-DD or a full ISO timestamp. A date-only to includes that whole day in the workspace timezone. Unscheduled drafts never match a date range. websiteState filters blog, FAQ and competitor posts by CMS delivery: preview (a pre-approval preview draft in the CMS, not live), queued, sent_to_cms (saved in the CMS, not live), published, taken_down, failed, removed, conflict, out_of_sync, or none: the same values as get_post's website.state. Optional timezone (IANA) renders scheduled and published times in that zone; it does not change stored data. Does not change anything. Related: get_post, approve_posts, review_post.

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

Input Schema

Name	Required	Description
`to`	No	Scheduled-to: YYYY-MM-DD (includes that whole day in the workspace timezone) or a full ISO timestamp.
`from`	No	Scheduled-from: YYYY-MM-DD (start of that day in the workspace timezone) or a full ISO timestamp.
`text`	No	Case-insensitive match in the body.
`limit`	No	How many rows to return. Default 20, max 100.
`cursor`	No	Opaque cursor from a previous call's nextCursor.
`status`	No	Filter by status. in_review is the review queue.
`angleId`	No	Angle id.
`channel`	No	Channel id, e.g. linkedin.
`pillarId`	No	Pillar id.
`timezone`	No	IANA zone to render times in. Does not change stored data. Defaults to the workspace timezone.
`websiteState`	No	Filter website posts by CMS delivery state: queued, sent_to_cms (saved in the CMS, not live), published, taken_down, failed, removed, conflict, out_of_sync, or none. Same values as get_post's website.state.

Output Schema

Name	Required	Description	Default
`more`	Yes
`items`	Yes
`nextCursor`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 30, 2026

changedOutput schema / properties / items / items / properties / handoff / description

Previous value: -"An approved social post's handoff to the publisher: handing_off (it moves to scheduled within seconds), stuck with the reason and fix (no scheduled time, no connected account for the channel, or no progress 5 minutes after approval), or null for every other status and every website post. An approved LinkedIn Article has no publisher: publish_by_hand before its scheduled time and publish_now from it on, until someone records its URL with record_post_published."New value: +"An approved social post's handoff to the publisher: handing_off (it moves to scheduled within seconds), stuck with the reason and fix (no scheduled time, no connected account for the channel, or no progress 5 minutes after approval), or null for every other status. An approved LinkedIn Article has no publisher: publish_by_hand before its scheduled time and publish_now from it on, until someone records its URL with record_post_published. An approved website post whose post type no CMS maps reads publish_by_hand (get_post and the review page only); every other website post is null."

Changed2 schema fields changedOct 24, 2026

changedInput schema / properties / status / description

Previous value: -"Filter by status. awaiting_review is the review queue."New value: +"Filter by status. in_review is the review queue."

changedInput schema / properties / status / enum

Previous value: -[
-  "draft",
-  "in_review",
-  "awaiting_review",
-  "approved",
-  "scheduled",
-  "published",
-  "changes_requested",
-  "rejected",
-  "failed",
-  "missed"
-]New value: +[
+  "draft",
+  "in_review",
+  "approved",
+  "scheduled",
+  "published",
+  "changes_requested",
+  "rejected",
+  "failed",
+  "missed"
+]

Changed2 schema fields changedOct 22, 2026

addedOutput schema / properties / items / items / properties / mediaCount

Added value: +{
+  "description": "Media on the post: assets, a website cover and images from the CMS. 0 means none.",
+  "type": "number"
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "angleId",
-  "appUrl",
-  "buyerQuestions",
-  "channel",
-  "excerpt",
-  "handoff",
-  "id",
-  "pillarId",
-  "publishedAt",
-  "refresh",
-  "rev",
-  "scheduledAt",
-  "status",
-  "updatedAt"
-]New value: +[
+  "angleId",
+  "appUrl",
+  "buyerQuestions",
+  "channel",
+  "excerpt",
+  "handoff",
+  "mediaCount",
+  "id",
+  "pillarId",
+  "publishedAt",
+  "refresh",
+  "rev",
+  "scheduledAt",
+  "status",
+  "updatedAt"
+]

Changed2 schema fields changedOct 20, 2026

changedOutput schema / properties / items / items / properties / handoff / anyOf

Previous value: -[
-  {
-    "oneOf": [
-      {
-        "additionalProperties": false,
-        "properties": {
-          "state": {
-            "const": "handing_off",
-            "type": "string"
-          }
-        },
-        "required": [
-          "state"
-        ],
-        "type": "object"
-      },
-      {
-        "additionalProperties": false,
-        "properties": {
-          "reason": {
-            "type": "string"
-          },
-          "state": {
-            "const": "stuck",
-            "type": "string"
-          }
-        },
-        "required": [
-          "reason",
-          "state"
-        ],
-        "type": "object"
-      }
-    ]
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "oneOf": [
+      {
+        "additionalProperties": false,
+        "properties": {
+          "state": {
+            "const": "handing_off",
+            "type": "string"
+          }
+        },
+        "required": [
+          "state"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "reason": {
+            "type": "string"
+          },
+          "state": {
+            "const": "stuck",
+            "type": "string"
+          }
+        },
+        "required": [
+          "reason",
+          "state"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "reason": {
+            "type": "string"
+          },
+          "state": {
+            "const": "publish_by_hand",
+            "type": "string"
+          }
+        },
+        "required": [
+          "reason",
+          "state"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "reason": {
+            "type": "string"
+          },
+          "state": {
+            "const": "publish_now",
+            "type": "string"
+          }
+        },
+        "required": [
+          "reason",
+          "state"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / items / items / properties / handoff / description

Previous value: -"An approved social post's handoff to the publisher: handing_off (it moves to scheduled within seconds), stuck with the reason and fix (no scheduled time, no connected account for the channel, or no progress 5 minutes after approval), or null for every other status and every website post."New value: +"An approved social post's handoff to the publisher: handing_off (it moves to scheduled within seconds), stuck with the reason and fix (no scheduled time, no connected account for the channel, or no progress 5 minutes after approval), or null for every other status and every website post. An approved LinkedIn Article has no publisher: publish_by_hand before its scheduled time and publish_now from it on, until someone records its URL with record_post_published."

Changed2 schema fields changedOct 19, 2026

changedInput schema / properties / websiteState / description

Previous value: -"Filter website posts by CMS delivery state: queued, draft (saved in the CMS, not live), published, failed, removed, conflict, out_of_sync, or none. Same values as get_post's website.state."New value: +"Filter website posts by CMS delivery state: queued, sent_to_cms (saved in the CMS, not live), published, taken_down, failed, removed, conflict, out_of_sync, or none. Same values as get_post's website.state."

changedInput schema / properties / websiteState / enum

Previous value: -[
-  "preview",
-  "queued",
-  "draft",
-  "published",
-  "failed",
-  "removed",
-  "conflict",
-  "out_of_sync",
-  "none"
-]New value: +[
+  "preview",
+  "queued",
+  "sent_to_cms",
+  "published",
+  "taken_down",
+  "failed",
+  "removed",
+  "conflict",
+  "out_of_sync",
+  "none"
+]

Changed2 schema fields changedOct 17, 2026

addedOutput schema / properties / items / items / properties / handoff

Added value: +{
+  "anyOf": [
+    {
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "state": {
+              "const": "handing_off",
+              "type": "string"
+            }
+          },
+          "required": [
+            "state"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "reason": {
+              "type": "string"
+            },
+            "state": {
+              "const": "stuck",
+              "type": "string"
+            }
+          },
+          "required": [
+            "reason",
+            "state"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "An approved social post's handoff to the publisher: handing_off (it moves to scheduled within seconds), stuck with the reason and fix (no scheduled time, no connected account for the channel, or no progress 5 minutes after approval), or null for every other status and every website post."
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "angleId",
-  "appUrl",
-  "buyerQuestions",
-  "channel",
-  "excerpt",
-  "id",
-  "pillarId",
-  "publishedAt",
-  "refresh",
-  "rev",
-  "scheduledAt",
-  "status",
-  "updatedAt"
-]New value: +[
+  "angleId",
+  "appUrl",
+  "buyerQuestions",
+  "channel",
+  "excerpt",
+  "handoff",
+  "id",
+  "pillarId",
+  "publishedAt",
+  "refresh",
+  "rev",
+  "scheduledAt",
+  "status",
+  "updatedAt"
+]

Changed3 schema fields changedOct 14, 2026

changedInput schema / properties / websiteState / enum

Previous value: -[
-  "queued",
-  "draft",
-  "published",
-  "failed",
-  "removed",
-  "conflict",
-  "out_of_sync",
-  "none"
-]New value: +[
+  "preview",
+  "queued",
+  "draft",
+  "published",
+  "failed",
+  "removed",
+  "conflict",
+  "out_of_sync",
+  "none"
+]

addedOutput schema / properties / items / items / properties / refresh

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "pageUrl": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "pageUrl",
+        "text"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "angleId",
-  "appUrl",
-  "buyerQuestions",
-  "channel",
-  "excerpt",
-  "id",
-  "pillarId",
-  "publishedAt",
-  "rev",
-  "scheduledAt",
-  "status",
-  "updatedAt"
-]New value: +[
+  "angleId",
+  "appUrl",
+  "buyerQuestions",
+  "channel",
+  "excerpt",
+  "id",
+  "pillarId",
+  "publishedAt",
+  "refresh",
+  "rev",
+  "scheduledAt",
+  "status",
+  "updatedAt"
+]

Changed2 schema fields changedOct 13, 2026

addedOutput schema / properties / items / items / properties / buyerQuestions

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "question": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "question"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / items / items / required

Previous value: -[
-  "angleId",
-  "appUrl",
-  "channel",
-  "excerpt",
-  "id",
-  "pillarId",
-  "publishedAt",
-  "rev",
-  "scheduledAt",
-  "status",
-  "updatedAt"
-]New value: +[
+  "angleId",
+  "appUrl",
+  "buyerQuestions",
+  "channel",
+  "excerpt",
+  "id",
+  "pillarId",
+  "publishedAt",
+  "rev",
+  "scheduledAt",
+  "status",
+  "updatedAt"
+]

Changed1 schema field changedOct 12, 2026

addedInput schema / properties / websiteState

Added value: +{
+  "description": "Filter website posts by CMS delivery state: queued, draft (saved in the CMS, not live), published, failed, removed, conflict, out_of_sync, or none. Same values as get_post's website.state.",
+  "enum": [
+    "queued",
+    "draft",
+    "published",
+    "failed",
+    "removed",
+    "conflict",
+    "out_of_sync",
+    "none"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 8, 2026

addedInput schema / properties / timezone

Added value: +{
+  "description": "IANA zone to render times in. Does not change stored data. Defaults to the workspace timezone.",
+  "type": "string"
+}

Changed2 schema fields changedOct 8, 2026

changedInput schema / properties / from / description

Previous value: -"Scheduled-from ISO date."New value: +"Scheduled-from: YYYY-MM-DD (start of that day in the workspace timezone) or a full ISO timestamp."

changedInput schema / properties / to / description

Previous value: -"Scheduled-to ISO date."New value: +"Scheduled-to: YYYY-MM-DD (includes that whole day in the workspace timezone) or a full ISO timestamp."

First observedOct 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantial non-obvious behavior: 'status: approved still matches handing-off, stuck, publish_by_hand and publish_now posts', rev staying 0 on drafts until submission, and the handoff lifecycle including what 'stuck' means and why. These are exactly the surprises an agent would otherwise misread.

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 the search axes and the highest-value caveat (mediaCount, so no per-post get_post). It is long and dense, and a fair amount of length re-explains return fields (rev, refresh, handoff, mediaCount) that the output schema already covers, plus websiteState values that the schema enum repeats verbatim.

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 an 11-parameter, zero-required search tool with subtle status and CMS-state semantics, the description covers the traps an agent must know: date filtering semantics, unscheduled drafts, approved matching multiple handoff states, and timezone being render-only. Nothing needed to call it correctly is missing.

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, but the description earns more: it clarifies that from/to filter on scheduled time 'not created or updated', that a date-only 'to' includes the whole day in workspace timezone, and that unscheduled drafts never match a date range. These are common misuse traps the schema alone does not flag as emphatically.

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+resource ('Finds posts') and enumerates the exact filter axes (status, channel, scheduled time range, angle, pillar, text, website CMS delivery state). This clearly separates it from get_post (single-post fetch), review_post, and approve_posts, which mutate or narrow to one item.

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?

Gives real usage context: 'in_review is the review queue', and explicitly says finding posts without an image needs no get_post per post, which steers an agent away from an N+1 pattern. It also states 'Does not change anything.' However the 'Related:' list is bare names with no conditionals attached, so the agent must infer when to switch to get_post or review_post instead.

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

All Mark 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?