Configured tool · read-only

`get_best_posts`

Rank one account's posts by one evidence-backed metric over a requested window.

read-onlynon-destructiveclosed-world

Human and agent roles

Configured boundary

Null observations are excluded with a stated reason. They are never ranked as zero.

This reference describes a connection made with @postdom/mcp@0.3.0 and a workspace-scoped agent key created in Accounts.

Callable schema

Field names match the configured tool schema. Runtime-only constraints are labeled separately from schema validation.

FieldTypeContract

account_idRequired

string

Connected account in this workspace

The account whose published destinations are compared.

metricRequired

metric

One normalized Postdom metric

The single evidence-backed value used for ranking.

windowOptional

7d | 30d

Defaults to 7d

Rolling publication window ending at observation time.

Synthetic values

Identifiers and values are examples. They do not represent a connected workspace or accepted media source.

EXAMPLE CALL · CONFIGURED TOOL SCHEMA

get_best_posts({
  account_id: "acct_example_ig",
  metric: "watch_time_s",
  window: "30d"
})

Observed API record

Returns ranked posts and explicitly excluded posts for the same metric and period.

account_id · metric · window · periodscope: Exact account, metric, rolling window, UTC bounds, and account timezone.
rankedarray: Only posts with a non-null evidence-backed value, ordered descending.
ranked[].rank · metricevidence number: Value plus availability, observation time, and source.
excludedarray: Published destinations omitted from ranking because the selected metric is null or unobserved.
excluded[].metric.availability.reasonstring: Why that post could not be ranked.

Stop conditions

ranked

Preserve the metric, period, rank, and evidence metadata.

excluded

Return each exclusion reason instead of inventing a zero.

empty

Do not infer a winner when no post has an available value.