Skip to main content
Glama
Facebook Pages MCP Server

Facebook Pages MCP Server

by asrrin29

page_insights

Read-onlyIdempotent

Read Page-level metrics such as reach, engagement, follower growth, video views, reactions, and demographics for a chosen period or date range.

Instructions

Read Page metrics Read Page-level metrics (reach, engagements, follower growth, video views, reactions, demographics). Pass one or more metric names, a period (day, week, days_28, lifetime) and either date_preset or since/until. Call page_insights_metrics for a list of metric names to try. Graph API: GET {page_id}/insights. Requires a token that can perform the ANALYZE task, and Pages with fewer than 100 likes return no insights. Some metrics are deprecated in newer API versions; an invalid-metric error names the metric that failed.

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": {
      "page_id": "<page_id>",
      "metrics": "<metrics>"
    },
    "name": "page_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
sinceNo
totalNo
untilNo
periodNo
metricsYes
page_idYes
breakdownNo
date_presetNo
access_tokenNoOptional Facebook Page access token for this call only. Use it when the token you hold is not the one this server was configured with, or when the configured token has expired. Takes effect for this call and nothing else. Also accepted as token or page_token.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.6.1

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful context beyond them: the required ANALYZE token task, the empty-result condition for Pages under 100 likes, API-version deprecation of some metrics, and the fact that an invalid-metric error names the offending metric. These are exactly the operational failure modes an agent needs before calling.

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 purpose, then endpoint, then prerequisites and edge cases — a sensible order with no filler sentences. The only blemish is the duplicated lead-in ("Read Page metrics Read Page-level metrics"), which suggests a stitched-together artifact rather than a drafted description.

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?

For a 9-parameter, read-only analytics call with an output schema (so return shape needn't be described), the definition covers purpose, endpoint, auth, period semantics, and error behavior. The remaining gap is the undocumented `total` and `breakdown` parameters, which materially affect aggregation and segmentation of results.

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 only 11%, so the description must compensate, and it does so partially: it explains metrics, period values, and the date_preset vs since/until mutual choice. But `total`, `breakdown`, `since`/`until` typing (epoch integers), and `page_id` meaning are left undocumented in both schema and prose, so roughly a third of the parameters remain opaque.

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 verb and resource ("Read Page-level metrics"), enumerates the metric families covered (reach, engagements, follower growth, video views, reactions, demographics), and gives the exact Graph API endpoint. It is clearly distinguishable from post_insights (post-level) and from page_insights_metrics, which it explicitly redirects to for metric discovery.

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 concrete invocation guidance: pass one or more metric names, a period from {day, week, days_28, lifetime}, and either date_preset or since/until. It names page_insights_metrics as the companion for finding valid metric names. It stops short of an explicit when-to-use-this-vs-post_insights rule, though "Page-level" implies the boundary.

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