Markaestro

Official

by markaestro

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

List post analytics

list_post_analytics

Read-onlyIdempotent

List posts in a date window with latest views, reach, likes, comments, shares, saves, clicks, and engagement rate; sort by engagements or views to find what worked.

Instructions

Every post in the window (the connection's brand, or on an all-brands connection the workspace or the brand named by productId) with its latest metrics (views, reach, likes, comments, shares, saves, clicks, engagements, engagement rate), one row per post, sorted. Includes posts published directly on the platform; each row's source says markaestro or native (canTakeDown is informational: taking a live post down is done by the user in Markaestro, not by delete_post). Use sort=engagements or sort=views to find what worked; sort=published_at (default) for a chronological read. Pair with get_post for the full caption and media of a Markaestro post (native posts have externalUrl instead).

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

Input Schema

Name	Required	Description
`days`	No	Preset window ending today (UTC); default 28
`sort`	No	Descending; default published_at
`limit`	No	Default 100
`since`	No	Explicit range start, YYYY-MM-DD (UTC); needs until
`until`	No	Explicit range end, YYYY-MM-DD (UTC), inclusive
`source`	No	Only posts published through Markaestro, or only posts published directly on the platform; omit for the whole account
`channel`	No
`productId`	No	One brand, on an all-brands connection; omit for the whole workspace. A single-brand connection always reports its own brand.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.4.0Nov 4, 2026

changedInput schema / properties / channel / enum

Previous value: -[
-  "facebook",
-  "instagram",
-  "tiktok",
-  "threads",
-  "pinterest",
-  "linkedin",
-  "x"
-]New value: +[
+  "facebook",
+  "instagram",
+  "tiktok",
+  "threads",
+  "pinterest",
+  "linkedin",
+  "x",
+  "youtube"
+]

First observedv0.3.3Sep 27, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: native posts are included, each row's source field distinguishes markaestro vs native, and canTakeDown is explicitly informational because takedowns happen in Markaestro rather than via delete_post. It does not discuss metric freshness/staleness or pagination behavior past the limit, which keeps it below a 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?

Content is front-loaded with the core result shape, then sorting guidance, then the sibling pairing, so the agent's most important questions are answered first. The opening sentence is long and parenthesis-heavy (scope clause nested inside the resource clause), which slightly harms scannability but no sentence is filler.

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

Completeness3/5

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

For an 8-parameter analytics listing with no output schema, the description covers row shape, scope resolution, sorting, and the get_post follow-up well. It leaves notable gaps: nothing about whether metrics are stale or require refresh_analytics first, and nothing about behavior when limit is exceeded (truncation vs pagination).

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?

With 88% schema coverage the baseline is 3, and the description earns more by explaining the productId scoping model (single-brand connection always reports its own brand; omit for whole workspace) and the meaning of each sort enum in practical terms. The window concept behind days/since/until is referenced but the explicit-range interaction is left entirely to 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?

States a specific resource (every post in the window) with a specific payload (latest metrics: views, reach, likes, comments, shares, saves, clicks, engagements, engagement rate) and a row granularity (one row per post, sorted). It explicitly differentiates from siblings get_post (full caption and media) and delete_post (not for takedowns), so an agent can choose without opening schemas.

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?

Gives concrete routing guidance: sort=engagements or sort=views to find what worked, sort=published_at for a chronological read, and pair with get_post when captions/media are needed. It also states scope selection rules (connection's brand, workspace, or productId on an all-brands connection), which is the main ambiguity for this tool.

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