docs: README — list all 47 tools + honest about aggregation limits (v1.0.3)

[OussemaFr]

Why

Operator tested v1.0.2 on Claude Desktop (it works). While testing, they hit the "Compare engagement rates between Nike, Adidas, and Puma over the last month" example from this README — and noticed the API can only deliver that via multi-call orchestration. Two real gaps in the README:

1. Stale tool list — README listed 12 Facebook tools and said "More platforms coming soon: Instagram, TikTok, YouTube, Twitter". But Instagram is fully implemented (16 tools), and the Facebook surface also includes Search (5), Ads Library (5), Marketplace (7), and Media (1). 35 tools were undocumented in the README despite being implemented.
2. Aggregation overpromise — "Compare engagement rates over the last month" sounds like a single tool call. It isn't. Claude can answer it by chaining facebook_get_page_posts calls with pagination + per-post aggregation math, but on a busy page that hits the LLM's tool-call budget.

What's in this PR

Available Tools (47 tools across 8 categories)

Category	Tools
Facebook — Pages	5
Facebook — Groups	5
Facebook — Posts	6
Facebook — Search	5
Facebook — Ads Library	5
Facebook — Marketplace	7
Facebook — Media	1
Instagram — Profile	6
Instagram — Posts + Reels	4
Instagram — Discovery	3
Total	47

Each tool has a one-line description. Pricing-affecting params (e.g. exact_followers_count charging 5 credits) flagged in their tool entry.

Honest "Coming soon" footer

TikTok / X (Twitter) / LinkedIn / YouTube — matches the actual platform roadmap (project_platform_roadmap.md in memory).

Usage examples — split by call shape

Old section mixed cheap-single-call ("Monitor Nike's page") with hard-multi-call ("Compare engagement over the last month") without flagging the difference. New section splits into:

• Single-call patterns (fast, cheap) — credit cost noted per example
• Multi-call patterns — explicit about Claude orchestrating N calls + the cost implication

New "What this MCP server does NOT do" section

Four real limitations, named honestly:

Query shape	Why it's hard
"Engagement rate over the last 30 days" for a page	Paginated fetch + per-post aggregation — hits the LLM tool-call budget on busy pages
"Compare engagement rates between Brand A, B, C over the last month"	Same problem, 3×
Historical archive older than what Facebook itself serves	We surface what Facebook makes publicly visible
Server-side time-series (daily / weekly metrics)	Roadmap item: engagement-stats endpoint with built-in aggregation

Closes with: "If your use case maps to one of these patterns and you want the aggregation pre-computed, contact support — we're prioritizing the aggregation endpoint based on customer demand."

Version bump 1.0.2 → 1.0.3

The npm-displayed README updates only on publish, so bumping ensures the new README reaches existing npm-discovered customers next time they look up the package.

Out of scope

This is README + package.json only — no code changes. The actual aggregation endpoint (when prioritized based on customer demand) is a follow-up that lives in the main repo's api-scraping service, not here.

Operator publish step after merge

cd backend/mcp-server  # local checkout
git checkout main && git pull
npm publish
git tag v1.0.3 && git push origin v1.0.3

The MCP Registry auto-syncs from npm via the mcpName field within ~24h.