Which integrations are available for this server?

Allows searching public ads through the Facebook Ad Library, with filters such as country and status. Allows retrieving public Instagram profile data and recent posts via ScrapeCreators. Allows retrieving public TikTok profile data, with TikTok audience demographics also noted as a paid endpoint. Allows retrieving specific YouTube video transcripts while preserving track language.

How do I use ScrapeCreators MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ScrapeCreators MCP Server can you fetch the Instagram profile for @nasa?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ScrapeCreators MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

ScrapeCreators MCP Server & CLI

npm License YouTube LinkedIn

ScrapeCreators MCP server and CLI for Codex and AI agents. 190 tools: five local/account reads and 185 potentially paid calls for public social profiles, posts, transcripts, comments, ads and bounded research.

One package provides local MCP, the same operations as task CLI commands, and a bundled desktop .mcpb extension.

Built and maintained by Navid Moazzez. Complete installation and private account setup are in INSTALL.md.

The terminal illustrates shipped public research tools with sample data. It is a presentation preview, not a verified live-account request.

You need a private ScrapeCreators API key and sufficient provider access/credits. This community product is maintained by Navid Media and preserves AGPL-3.0-or-later. ScrapeCreators already has an official CLI and hosted MCP; useful differences and limitations are compared below.

Two ways to use it

Command line

npm install -g @thenavidm/scrapecreators-mcp-cli@latest
scrapecreators-cli
scrapecreators-cli instagram-profile --help
scrapecreators-cli schema research-batch
scrapecreators-cli scrapecreators-get-credit-balance --agent

Configure private access before account calls. Potentially paid research requires --confirm; --yes and --agent do not authorize it.

MCP server, for your AI app

codex mcp add scrapecreators -- npx -y @thenavidm/scrapecreators-mcp-cli@latest

Then ask: Check credit balance, then show the exact public-profile lookup before I approve the paid call. Full client/OS setup is in INSTALL.md.

Which one

Where you work	Surface
Codex or another shell agent	Local MCP, shared CLI or both
Desktop chat	Compatible local MCP/.mcpb host
Scripts/CI	Shared task CLI or MCP client
Remote-URL-only client	Official provider hosted MCP

Related MCP server: instagram-mcp

Features

Capability	CLI	MCP
Public profiles	instagram-profile / tiktok-profile	instagram_profile / tiktok_profile
Video transcripts	youtube-transcript	youtube_transcript
Public ads	facebook-ad-library-search-post	facebook_ad_library_search_post
Account credit/history	scrapecreators-get-credit-balance	scrapecreators_get_credit_balance
Exact bounded research	research-batch	research_batch
Private account labels	list-accounts / --account	list_accounts / account
Setup diagnosis	doctor / login	CLI utilities

Number	Section	Covers
1	What you can ask it	Practical research
2	Quick install	Both binaries and desktop
3	Set up ScrapeCreators access	Keys, credits and caching
4	Connect your client	Clients and OS
5	Check it works	Doctor and first account read
6	Output, flags and exit codes	Schema-derived flags and scripting
7	MCP or CLI and token cost	Measured evidence requirements
8	Every tool and argument	All current tools and arguments
9	Creator, transcript and ad research workflows	Profiles, transcripts, ads and batch
10	Pagination, credits and request budgets	Opaque cursors and actual charges
11	Several private accounts	Named credentials
12	Approving paid research safely	Per-call approval and policies
13	How it works	Shared handlers and schema sync
14	Your data	Direct API and privacy
15	Environment variables	Private credentials and tuning
16	Updates and removal	Upgrade and revoke
17	Troubleshooting	Errors and remedies
18	API coverage and comparisons	Official and community choices
19	Versions	Release and migration history
20	FAQ	Accordion answers

1. What you can ask it

Inspect a selected public creator profile and one page of recent posts.
Retrieve the specific YouTube transcript I approved, preserving track language.
Research matching public ads in the chosen country and status.
Compare a bounded set of public profiles in one named private account.
Check credit balance and account request history before repeating a failed lookup.

The current schema supplies 188 API operations across 37 groups. list_accounts is local; research_batch is a shared local workflow. Actual discovery gives 190 tools: five local/account reads and 185 potentially paid calls. Account metadata remains available in read-only mode; paid research requires explicit confirmation, even for GET.

ScrapeCreators already offers official MCP, CLI and research skills. This owned wrapper adds enforced paid-call approval, named private credentials and bounded prevalidated batches. Fixture/protocol validation is separate from live account outcomes, GUI installation and measured token evidence.

2. Quick install

npm install -g @thenavidm/scrapecreators-mcp-cli@latest
scrapecreators-cli --version
scrapecreators-cli login
scrapecreators-cli doctor
scrapecreators-cli tools

Node 22+ is required for manual CLI/MCP setup. Discovery, schemas and list_accounts work without a key. The scrapecreators-2.0.0.mcpb desktop archive bundles production dependencies for a compatible host. Full setup is in INSTALL.md.

After private environment configuration:

codex mcp add scrapecreators -- npx -y @thenavidm/scrapecreators-mcp-cli@latest
codex mcp list

3. Set up ScrapeCreators access

Private API key

Sign in to the intended account at app.scrapecreators.com and open its API Keys area.
Retrieve or create the key for the intended account/team. API access uses your ScrapeCreators key, not social-platform passwords, cookies or a GitHub CLI token.
Save the key in a private token-only file outside repositories, then set SCRAPECREATORS_TOKEN_FILE to its absolute path. SCRAPECREATORS_API_KEY in private local client/shell settings is the alternative.
Run scrapecreators-cli doctor, then scrapecreators-cli doctor --network. Network doctor reads current account credit metadata and prints no account details.
Check the required endpoint, available balance and approved task before any potentially paid research call.

Requests use x-api-key, with the fixed origin https://api.scrapecreators.com. Routes retain their current v1/v2/v3 prefixes. There is no invented dated-version header. login prints instructions; it does not sign up, save credentials or complete OAuth. The official hosted MCP supports its own OAuth/API-key flow, and the official CLI provides interactive key setup and GitHub device signup. Those are separate products, not hidden features of this wrapper.

On macOS/Linux, use an owner-only key file (0600) in a private directory (0700). On Windows, restrict its ACL to your user. Files must be regular, not symlinks, and no larger than 64 KB. A file overrides the environment key and is cached until restart. GUI client settings and terminal environments are separate. Never place actual credentials in chat, command arguments, project config, issues or examples. This package does not automatically load .env files or use an OS keychain.

Access, pricing and quotas

A ScrapeCreators account with API access and enough credits is required; installing this free AGPL wrapper does not purchase data. The provider pricing page, checked October 2, 2026, lists 100 starting credits, $47 for 25,000 credits and $497 for 500,000 credits, with no mandatory subscription and nonexpiring purchased credits. Bonus/device-signup allowances have different conditions; check your actual dashboard. No universal social-platform admin role or OAuth scope list is imposed by this API-key wrapper.

Most live research requests cost one credit, but current endpoint exceptions include TikTok audience demographics (26) and Find Social Profiles (10). A supported cache hit costs zero; a miss can use the normal endpoint charge. Do not treat max_calls as a credit or money limit. Check response credits_charged, cached and cached_at where supplied, and the account request history. Provider pricing can change.

The provider advertises no account-level rate/concurrency cap. Local pacing defaults to 150 ms between calls per account/process as a reliability choice, not a provider quota rule or reservation. Sequential batches cap at 20 explicit calls. Research GET and POST requests never retry automatically; a lost response can still have consumed credits. Only account-metadata GET 429 responses can retry, at most two by default, for Retry-After waits of ten seconds or less. Longer waits return exit 7. No failed-call billing guarantee is invented.

Provider caching and public-data limits

Only endpoints whose schema includes cache_max_age accept that option here: 1d, 3d, 7d, 14d or 30d. A cache hit is older data, so retain its timestamp. Team owners can disable provider caching on the API Keys page; then the option does not guarantee a hit or zero credits. See the cache documentation.

This is public-data research, not social-platform publishing or a bypass for private profiles. Availability, geographic results, transcript tracks, cursor validity and upstream platform changes affect results. Account metadata/history can reveal private usage. Choose only the requested public resources and keep returned personal or business data out of public logs.

4. Connect your client

INSTALL.md retains the established client setup for Codex, Claude Code, Claude Desktop extension/manual config, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other stdio clients on macOS, Windows and Linux. Codex is the current priority; Claude Code is optional.

Use command npx with arguments -y, @thenavidm/scrapecreators-mcp-cli@latest, and private local credential settings. Remote-only clients can use the provider's official https://api.scrapecreators.com/mcp endpoint with its supported OAuth/API-key connection. This local package has no public HTTP relay.

The shipped SKILL.md guides a shell agent. Make it available through the client's supported skills location; npm installation alone does not register it. Client approval and confirm=true are separate: the guard requires approval for this specific paid action, not permission inferred from returned content.

5. Check it works

scrapecreators-cli --version
scrapecreators-cli doctor
scrapecreators-cli doctor --network
scrapecreators-cli list-accounts --agent
scrapecreators-cli scrapecreators-get-credit-balance --agent

Network doctor performs GET /v1/account/credit-balance and reports authentication without account content. A successful account read proves that request, not every public-data endpoint. Full discovery exposes 190 tools, read-only exposes five. Missing configuration exits 10; invalid arguments and refused paid research exit 2.

For an approved first research request, use a public handle you selected and an acceptable cache age:

scrapecreators-cli instagram-profile --handle PUBLIC_HANDLE --cache-max-age 7d --confirm --agent

6. Output, flags and exit codes

Tool names become dashed commands; underscores are accepted too. Path parameter names follow the discovered schema, such as continuationToken → --continuation-token. Body tools accept individual top-level flags, complete --payload JSON, or --payload-file pointing to a regular JSON body file up to 5 MB. Do not mix those body routes. Path/query flags remain separate. Nested objects take JSON and array flags repeat once per item; a whole array is not a single item.

scrapecreators-cli instagram-profile --help
scrapecreators-cli schema reddit-post-comments-post
scrapecreators-cli youtube-comments --url "https://www.youtube.com/watch?v=VIDEO_ID" --continuation-token OPAQUE_TOKEN --confirm --agent

IDs/cursors above are illustrative; use the selected public resource and cursor from its prior response. Nullable fields require an actual JSON null inside payload; --field null is a string. Nested values preserve current upstream constraints; unknown top-level body fields are refused. Body-required fields are validated during execution even when the wrapper schema allows an alternative payload route. Operations whose upstream request body is required need body flags or an explicit payload; a deliberately supplied empty object is sent as JSON, never omitted.

Flag	Behavior
--help / schema COMMAND	Current argument help / full JSON Schema
--json	Structured JSON
--compact	One-line JSON
--agent	Compact JSON, no prompts or color
--select a,b.c	Keep selected fields, including nested objects/arrays
--no-color / --no-input	Noninteractive house flags
--yes	Never replaces paid-call confirmation
--confirm	Approve only the requested paid research
--account NAME	Select private local credentials
--payload JSON / --payload-file PATH	Complete request body, mutually exclusive with body flags

Exit	Meaning
0	Success
2	Invalid arguments or refused paid call
3	Resource not found
4	Authentication/permission failure
5	API/transport failure
7	Rate limit
10	Missing or invalid private configuration

Results go to stdout, errors as JSON to stderr. Selection changes local output, not the original API response or provider charge. API success is not proof that public data is current, exhaustive or complete.

7. MCP or CLI and token cost

MCP and CLI use the same SDK server, schemas, validation and HTTP handlers. The CLI talks to that server through the SDK's in-memory transport; there is no second API implementation.

Measurement	What to include
Eager MCP loading	All tool schemas and instructions
Default/deferred tool search	Actual selected schemas and discovery overhead
Skill read once	Full SKILL.md and command discovery
Recurring skill discovery	The installed skill's listing text
Matched successful task	Help/schema, reasoning, calls/commands, results, errors and retries

Fresh Codex usage measurements are pending. Claude Code measurements are deferred and do not block this release. Do not estimate tokens from characters, substitute another repo's results or declare zero CLI cost. Record model/client/package versions and date, loading settings, input/output usage, latency and equivalent outcomes. Compare a small public-profile lookup and a bounded transcript research task across supported official/local surfaces, using the same authorized data and result fields. API credits and service costs remain separate. No measured superiority is claimed.

8. Every tool and argument

The full current API catalogue and every argument below derive from actual stdio discovery. The API has 188 endpoint variants; the local helpers bring discovery to 190. Read-like POST requests retrieve data rather than publish social content. Query/body field names preserve the upstream schema, including native camelCase cursors.

Tool	Route	Mode
`tiktok_profile`	`GET /v1/tiktok/profile`	Potentially paid; confirm
`tiktok_profile_region`	`GET /v1/tiktok/profile/region`	Potentially paid; confirm
`tiktok_audience_demographics`	`GET /v1/tiktok/user/audience`	Potentially paid; confirm
`tiktok_collection_videos`	`GET /v1/tiktok/collection/videos`	Potentially paid; confirm
`tiktok_profile_videos`	`GET /v3/tiktok/profile/videos`	Potentially paid; confirm
`tiktok_video_info`	`GET /v2/tiktok/video`	Potentially paid; confirm
`tiktok_transcript`	`GET /v1/tiktok/video/transcript`	Potentially paid; confirm
`tiktok_live`	`GET /v1/tiktok/user/live`	Potentially paid; confirm
`tiktok_live_info`	`GET /v1/tiktok/live`	Potentially paid; confirm
`tiktok_comments`	`GET /v1/tiktok/video/comments`	Potentially paid; confirm
`tiktok_comment_replies`	`GET /v1/tiktok/video/comment/replies`	Potentially paid; confirm
`tiktok_following`	`GET /v1/tiktok/user/following`	Potentially paid; confirm
`tiktok_followers`	`GET /v1/tiktok/user/followers`	Potentially paid; confirm
`tiktok_search_users`	`GET /v1/tiktok/search/users`	Potentially paid; confirm
`tiktok_search_suggestions`	`GET /v1/tiktok/search/suggestions`	Potentially paid; confirm
`tiktok_search_by_hashtag`	`GET /v1/tiktok/search/hashtag`	Potentially paid; confirm
`tiktok_search_by_keyword`	`GET /v1/tiktok/search/keyword`	Potentially paid; confirm
`tiktok_top_search`	`GET /v1/tiktok/search/top`	Potentially paid; confirm
`tiktok_get_popular_creators`	`GET /v1/tiktok/creators/popular`	Potentially paid; confirm
`tiktok_get_song_details`	`GET /v1/tiktok/song`	Potentially paid; confirm
`tiktok_tiktoks_using_song`	`GET /v1/tiktok/song/videos`	Potentially paid; confirm
`tiktok_trending_feed`	`GET /v1/tiktok/get-trending-feed`	Potentially paid; confirm
`tiktok_shop_shop_search`	`GET /v1/tiktok/shop/search`	Potentially paid; confirm
`tiktok_shop_shop_products`	`GET /v1/tiktok/shop/products`	Potentially paid; confirm
`tiktok_shop_product_details`	`GET /v1/tiktok/product`	Potentially paid; confirm
`tiktok_shop_product_reviews`	`GET /v1/tiktok/shop/product/reviews`	Potentially paid; confirm
`tiktok_shop_user_showcase`	`GET /v1/tiktok/user/showcase`	Potentially paid; confirm
`instagram_profile`	`GET /v1/instagram/profile`	Potentially paid; confirm
`instagram_basic_profile`	`GET /v1/instagram/basic-profile`	Potentially paid; confirm
`instagram_posts`	`GET /v2/instagram/user/posts`	Potentially paid; confirm
`instagram_user_tagged_posts`	`GET /v1/instagram/user/tagged-posts`	Potentially paid; confirm
`instagram_reels`	`GET /v1/instagram/user/reels`	Potentially paid; confirm
`instagram_post_reel_info`	`GET /v1/instagram/post`	Potentially paid; confirm
`instagram_transcript`	`GET /v2/instagram/media/transcript`	Potentially paid; confirm
`instagram_search_instagram`	`GET /v1/instagram/search`	Potentially paid; confirm
`instagram_popular_search`	`GET /v1/instagram/search/popular`	Potentially paid; confirm
`instagram_search_hashtag_posts`	`GET /v1/instagram/search/hashtag`	Potentially paid; confirm
`instagram_search_instagram_profiles`	`GET /v1/instagram/search/profiles`	Potentially paid; confirm
`instagram_search_reels`	`GET /v2/instagram/reels/search`	Potentially paid; confirm
`instagram_get_reels_by_audio_id`	`GET /v1/instagram/audio/reels`	Potentially paid; confirm
`instagram_trending_reels`	`GET /v1/instagram/reels/trending`	Potentially paid; confirm
`instagram_comments`	`GET /v2/instagram/post/comments`	Potentially paid; confirm
`instagram_comment_replies`	`GET /v1/instagram/post/comment/replies`	Potentially paid; confirm
`instagram_story_highlights`	`GET /v1/instagram/user/highlights`	Potentially paid; confirm
`instagram_highlights_details`	`GET /v1/instagram/user/highlight/detail`	Potentially paid; confirm
`instagram_profile_post_count`	`GET /v1/instagram/profile/post-count`	Potentially paid; confirm
`instagram_embed_html`	`GET /v1/instagram/user/embed`	Potentially paid; confirm
`telegram_channel_details`	`GET /v1/telegram/channel`	Potentially paid; confirm
`telegram_channel_posts`	`GET /v1/telegram/channel/posts`	Potentially paid; confirm
`telegram_post_details`	`GET /v1/telegram/post`	Potentially paid; confirm
`youtube_channel_details`	`GET /v1/youtube/channel`	Potentially paid; confirm
`youtube_channel_videos`	`GET /v1/youtube/channel-videos`	Potentially paid; confirm
`youtube_channel_playlists`	`GET /v1/youtube/channel/playlists`	Potentially paid; confirm
`youtube_channel_lives`	`GET /v1/youtube/channel/lives`	Potentially paid; confirm
`youtube_channel_community_posts`	`GET /v1/youtube/channel/community-posts`	Potentially paid; confirm
`youtube_channel_shorts`	`GET /v1/youtube/channel/shorts`	Potentially paid; confirm
`youtube_video_short_details`	`GET /v1/youtube/video`	Potentially paid; confirm
`youtube_transcript`	`GET /v1/youtube/video/transcript`	Potentially paid; confirm
`youtube_video_sponsors`	`GET /v1/youtube/video/sponsors`	Potentially paid; confirm
`youtube_search`	`GET /v1/youtube/search`	Potentially paid; confirm
`youtube_search_typeahead`	`GET /v1/youtube/search/typeahead`	Potentially paid; confirm
`youtube_search_by_hashtag`	`GET /v1/youtube/search/hashtag`	Potentially paid; confirm
`youtube_comments`	`GET /v1/youtube/video/comments`	Potentially paid; confirm
`youtube_comment_replies`	`GET /v1/youtube/video/comment/replies`	Potentially paid; confirm
`youtube_trending_shorts`	`GET /v1/youtube/shorts/trending`	Potentially paid; confirm
`youtube_playlist`	`GET /v1/youtube/playlist`	Potentially paid; confirm
`youtube_community_post_details`	`GET /v1/youtube/community-post`	Potentially paid; confirm
`rumble_search`	`GET /v1/rumble/search`	Potentially paid; confirm
`rumble_channel_videos`	`GET /v1/rumble/channel/videos`	Potentially paid; confirm
`rumble_video`	`GET /v1/rumble/video`	Potentially paid; confirm
`rumble_transcript`	`GET /v1/rumble/video/transcript`	Potentially paid; confirm
`rumble_comments`	`GET /v1/rumble/video/comments`	Potentially paid; confirm
`linkedin_person_profile`	`GET /v1/linkedin/profile`	Potentially paid; confirm
`linkedin_company_page`	`GET /v1/linkedin/company`	Potentially paid; confirm
`linkedin_company_posts`	`GET /v1/linkedin/company/posts`	Potentially paid; confirm
`linkedin_search_posts`	`GET /v1/linkedin/search/posts`	Potentially paid; confirm
`linkedin_post`	`GET /v1/linkedin/post`	Potentially paid; confirm
`linkedin_post_transcript`	`GET /v1/linkedin/post/transcript`	Potentially paid; confirm
`facebook_profile`	`GET /v1/facebook/profile`	Potentially paid; confirm
`facebook_profile_reels`	`GET /v1/facebook/profile/reels`	Potentially paid; confirm
`facebook_profile_photos`	`GET /v1/facebook/profile/photos`	Potentially paid; confirm
`facebook_profile_posts`	`GET /v1/facebook/profile/posts`	Potentially paid; confirm
`facebook_profile_events`	`GET /v1/facebook/profile/events`	Potentially paid; confirm
`facebook_post`	`GET /v1/facebook/post`	Potentially paid; confirm
`facebook_transcript`	`GET /v1/facebook/post/transcript`	Potentially paid; confirm
`facebook_comments`	`GET /v1/facebook/post/comments`	Potentially paid; confirm
`facebook_comment_replies`	`GET /v1/facebook/post/comment/replies`	Potentially paid; confirm
`facebook_facebook_group_info`	`GET /v1/facebook/group`	Potentially paid; confirm
`facebook_facebook_group_posts`	`GET /v1/facebook/group/posts`	Potentially paid; confirm
`github_user`	`GET /v1/github/user`	Potentially paid; confirm
`github_repositories`	`GET /v1/github/user/repositories`	Potentially paid; confirm
`github_pull_requests`	`GET /v1/github/user/pull-requests`	Potentially paid; confirm
`github_activity`	`GET /v1/github/user/activity`	Potentially paid; confirm
`github_followers`	`GET /v1/github/user/followers`	Potentially paid; confirm
`github_following`	`GET /v1/github/user/following`	Potentially paid; confirm
`github_contributions`	`GET /v1/github/user/contributions`	Potentially paid; confirm
`github_repository`	`GET /v1/github/repository`	Potentially paid; confirm
`github_trending_repositories`	`GET /v1/github/trending/repositories`	Potentially paid; confirm
`github_trending_developers`	`GET /v1/github/trending/developers`	Potentially paid; confirm
`facebook_marketplace_marketplace_location_search`	`GET /v1/facebook/marketplace/location/search`	Potentially paid; confirm
`facebook_marketplace_marketplace_search`	`GET /v1/facebook/marketplace/search`	Potentially paid; confirm
`facebook_marketplace_marketplace_item`	`GET /v1/facebook/marketplace/item`	Potentially paid; confirm
`facebook_events_search_events`	`GET /v1/facebook/events/search`	Potentially paid; confirm
`facebook_events_events`	`GET /v1/facebook/events`	Potentially paid; confirm
`facebook_events_event_details`	`GET /v1/facebook/event/details`	Potentially paid; confirm
`facebook_ad_library_ad_details`	`GET /v1/facebook/adLibrary/ad`	Potentially paid; confirm
`facebook_ad_library_ad_transcript`	`GET /v1/facebook/adLibrary/ad/transcript`	Potentially paid; confirm
`facebook_ad_library_search`	`GET /v1/facebook/adLibrary/search/ads`	Potentially paid; confirm
`facebook_ad_library_search_post`	`POST /v1/facebook/adLibrary/search/ads`	Potentially paid; confirm
`facebook_ad_library_company_ads`	`GET /v1/facebook/adLibrary/company/ads`	Potentially paid; confirm
`facebook_ad_library_company_ads_post`	`POST /v1/facebook/adLibrary/company/ads`	Potentially paid; confirm
`facebook_ad_library_search_for_companies`	`GET /v1/facebook/adLibrary/search/companies`	Potentially paid; confirm
`tiktok_ad_library_ad_library_search`	`GET /v1/tiktok/ad-library/search`	Potentially paid; confirm
`tiktok_ad_library_ad_library_ad`	`GET /v1/tiktok/ad-library/ad`	Potentially paid; confirm
`google_ad_library_company_ads`	`GET /v1/google/company/ads`	Potentially paid; confirm
`google_ad_library_ad_details`	`GET /v1/google/ad`	Potentially paid; confirm
`google_ad_library_advertiser_search`	`GET /v1/google/adLibrary/advertisers/search`	Potentially paid; confirm
`linkedin_ad_library_search_ads`	`GET /v1/linkedin/ads/search`	Potentially paid; confirm
`linkedin_ad_library_ad_details`	`GET /v1/linkedin/ad`	Potentially paid; confirm
`twitter_profile`	`GET /v1/twitter/profile`	Potentially paid; confirm
`twitter_user_tweets`	`GET /v1/twitter/user-tweets`	Potentially paid; confirm
`twitter_tweet_details`	`GET /v1/twitter/tweet`	Potentially paid; confirm
`twitter_transcript`	`GET /v1/twitter/tweet/transcript`	Potentially paid; confirm
`twitter_community`	`GET /v1/twitter/community`	Potentially paid; confirm
`twitter_community_tweets`	`GET /v1/twitter/community/tweets`	Potentially paid; confirm
`reddit_subreddit_details`	`GET /v1/reddit/subreddit/details`	Potentially paid; confirm
`reddit_subreddit_posts`	`GET /v1/reddit/subreddit`	Potentially paid; confirm
`reddit_subreddit_search`	`GET /v1/reddit/subreddit/search`	Potentially paid; confirm
`reddit_post`	`GET /v1/reddit/post`	Potentially paid; confirm
`reddit_post_comments`	`GET /v1/reddit/post/comments`	Potentially paid; confirm
`reddit_post_comments_post`	`POST /v1/reddit/post/comments`	Potentially paid; confirm
`reddit_post_transcript`	`GET /v1/reddit/post/transcript`	Potentially paid; confirm
`reddit_search`	`GET /v1/reddit/search`	Potentially paid; confirm
`truth_social_profile`	`GET /v1/truthsocial/profile`	Potentially paid; confirm
`truth_social_user_posts`	`GET /v1/truthsocial/user/posts`	Potentially paid; confirm
`truth_social_post`	`GET /v1/truthsocial/post`	Potentially paid; confirm
`threads_profile`	`GET /v1/threads/profile`	Potentially paid; confirm
`threads_posts`	`GET /v1/threads/user/posts`	Potentially paid; confirm
`threads_post`	`GET /v1/threads/post`	Potentially paid; confirm
`threads_search_by_keyword`	`GET /v1/threads/search`	Potentially paid; confirm
`threads_search_users`	`GET /v1/threads/search/users`	Potentially paid; confirm
`bluesky_profile`	`GET /v1/bluesky/profile`	Potentially paid; confirm
`bluesky_posts`	`GET /v1/bluesky/user/posts`	Potentially paid; confirm
`bluesky_post`	`GET /v1/bluesky/post`	Potentially paid; confirm
`pinterest_search`	`GET /v1/pinterest/search`	Potentially paid; confirm
`pinterest_pin`	`GET /v1/pinterest/pin`	Potentially paid; confirm
`pinterest_user_boards`	`GET /v1/pinterest/user/boards`	Potentially paid; confirm
`pinterest_board`	`GET /v1/pinterest/board`	Potentially paid; confirm
`google_search`	`GET /v1/google/search`	Potentially paid; confirm
`twitch_profile`	`GET /v1/twitch/profile`	Potentially paid; confirm
`twitch_user_videos`	`GET /v1/twitch/user/videos`	Potentially paid; confirm
`twitch_user_schedule`	`GET /v1/twitch/user/schedule`	Potentially paid; confirm
`twitch_clip_transcript`	`GET /v1/twitch/clip/transcript`	Potentially paid; confirm
`twitch_clip`	`GET /v1/twitch/clip`	Potentially paid; confirm
`apple_music_artist`	`GET /v1/apple-music/artist`	Potentially paid; confirm
`apple_music_album`	`GET /v1/apple-music/album`	Potentially paid; confirm
`apple_music_track`	`GET /v1/apple-music/track`	Potentially paid; confirm
`apple_music_search`	`GET /v1/apple-music/search`	Potentially paid; confirm
`spotify_artist`	`GET /v1/spotify/artist`	Potentially paid; confirm
`spotify_track`	`GET /v1/spotify/track`	Potentially paid; confirm
`spotify_album`	`GET /v1/spotify/album`	Potentially paid; confirm
`spotify_playlist`	`GET /v1/spotify/playlist`	Potentially paid; confirm
`spotify_search`	`GET /v1/spotify/search`	Potentially paid; confirm
`spotify_podcast`	`GET /v1/spotify/podcast`	Potentially paid; confirm
`spotify_podcast_episodes`	`GET /v1/spotify/podcast/episodes`	Potentially paid; confirm
`soundcloud_artist`	`GET /v1/soundcloud/artist`	Potentially paid; confirm
`soundcloud_artist_tracks`	`GET /v1/soundcloud/artist/tracks`	Potentially paid; confirm
`soundcloud_track`	`GET /v1/soundcloud/track`	Potentially paid; confirm
`kwai_profile`	`GET /v1/kwai/profile`	Potentially paid; confirm
`kwai_user_posts`	`GET /v1/kwai/user/posts`	Potentially paid; confirm
`kwai_post`	`GET /v1/kwai/post`	Potentially paid; confirm
`kick_clip_transcript`	`GET /v1/kick/clip/transcript`	Potentially paid; confirm
`kick_clip`	`GET /v1/kick/clip`	Potentially paid; confirm
`snapchat_user_profile`	`GET /v1/snapchat/profile`	Potentially paid; confirm
`snapchat_spotlight_by_link`	`GET /v1/snapchat/spotlight`	Potentially paid; confirm
`snapchat_spotlight_comments_by_link`	`GET /v1/snapchat/spotlight/comments`	Potentially paid; confirm
`creator_tools_find_social_profiles`	`GET /v1/find-social-profiles`	Potentially paid; confirm
`creator_tools_get_age_and_gender`	`GET /v1/detect-age-gender`	Potentially paid; confirm
`linktree_linktree_page`	`GET /v1/linktree`	Potentially paid; confirm
`komi_komi_page`	`GET /v1/komi`	Potentially paid; confirm
`pillar_pillar_page`	`GET /v1/pillar`	Potentially paid; confirm
`linkbio_linkbio_page`	`GET /v1/linkbio`	Potentially paid; confirm
`amazon_shop_amazon_shop_page`	`GET /v1/amazon/shop`	Potentially paid; confirm
`scrapecreators_get_credit_balance`	`GET /v1/account/credit-balance`	Account metadata read
`scrapecreators_get_request_history`	`GET /v1/account/get-api-usage`	Account metadata read
`scrapecreators_get_daily_usage`	`GET /v1/account/get-daily-usage-count`	Account metadata read
`scrapecreators_get_most_used_routes`	`GET /v1/account/get-most-used-routes`	Account metadata read
`linkme_profile`	`GET /v1/linkme`	Potentially paid; confirm
`list_accounts`	Local, no network	Read
`research_batch`	Local sequential workflow	Confirmed paid research

tiktok_profile

scrapecreators-cli tiktok-profile

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	TikTok handle. You can pass handle or user_id.
`user_id`	No; body/guard rules apply	string	TikTok user id.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

Provide handle or user_id; an empty selector is rejected before a network call.

tiktok_profile_region

scrapecreators-cli tiktok-profile-region

Argument	Required	Type	Details
`handle`	Yes	string	TikTok handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_audience_demographics

scrapecreators-cli tiktok-audience-demographics

Argument	Required	Type	Details
`handle`	Yes	string	TikTok handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_collection_videos

scrapecreators-cli tiktok-collection-videos

Argument	Required	Type	Details
`url`	Yes	string	Public TikTok collection URL
`cursor`	No; body/guard rules apply	string	Cursor to get more videos. Use max_cursor from the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_profile_videos

scrapecreators-cli tiktok-profile-videos

Argument	Required	Type	Details
`handle`	Yes	string	TikTok handle
`user_id`	No; body/guard rules apply	string	TikTok user id. Use this for faster responses.
`sort_by`	No; body/guard rules apply	string	What to sort by Values: `latest`, `popular`.
`max_cursor`	No; body/guard rules apply	string	Cursor to get more videos. Get 'max_cursor' from previous response.
`region`	No; body/guard rules apply	string	Region (country) for the proxy. Defaults to GB. If a profile should have videos but returns none, try US or another relevant two-letter country code.
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_video_info

scrapecreators-cli tiktok-video-info

Argument	Required	Type	Details
`url`	Yes	string	TikTok video URL
`get_transcript`	No; body/guard rules apply	boolean	Get transcript of the video
`region`	No; body/guard rules apply	string	Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`download_media`	No; body/guard rules apply	boolean	Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_transcript

scrapecreators-cli tiktok-transcript

Argument	Required	Type	Details
`url`	Yes	string	TikTok video URL
`language`	No; body/guard rules apply	string	Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'
`use_ai_as_fallback`	No; body/guard rules apply	string	Set to 'true' to use AI when an existing transcript is not found. The AI fallback supports videos up to 2 minutes and costs 10 credits; existing transcripts have no length limit.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_live

scrapecreators-cli tiktok-live

Argument	Required	Type	Details
`handle`	Yes	string	TikTok handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_live_info

scrapecreators-cli tiktok-live-info

Argument	Required	Type	Details
`room_id`	Yes	string	TikTok live room id. Get this from `/v1/tiktok/user/live` in `liveRoomUserInfo.roomId` or `liveRoom.id` when the user is live.
`user_id`	Yes	string	TikTok numeric user id for the live owner. Get this from `/v1/tiktok/profile` in `user.id`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_comments

scrapecreators-cli tiktok-comments

Argument	Required	Type	Details
`url`	Yes	string	TikTok video URL
`cursor`	No; body/guard rules apply	number	Cursor to get more comments. Get 'cursor' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_comment_replies

scrapecreators-cli tiktok-comment-replies

Argument	Required	Type	Details
`comment_id`	Yes	string	TikTok comment ID. This is the cid from the comments endpoint.
`url`	Yes	string	TikTok video URL. This is the url from the comments endpoint.
`cursor`	No; body/guard rules apply	number	Cursor to get more replies. Get 'cursor' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_following

scrapecreators-cli tiktok-following

Argument	Required	Type	Details
`handle`	Yes	string	TikTok handle
`min_time`	No; body/guard rules apply	number	Used to paginate. Get 'min_time' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_followers

scrapecreators-cli tiktok-followers

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	TikTok handle
`user_id`	No; body/guard rules apply	string	User id. Use this for faster response times.
`min_time`	No; body/guard rules apply	number	Used to paginate. Get 'min_time' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_search_users

scrapecreators-cli tiktok-search-users

Argument	Required	Type	Details
`query`	Yes	string	Search query for users
`cursor`	No; body/guard rules apply	number	Cursor to get more users. Get 'cursor' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_search_suggestions

scrapecreators-cli tiktok-search-suggestions

Argument	Required	Type	Details
`query`	Yes	string	Search query to get suggestions for
`region`	No; body/guard rules apply	string	Region code for suggestions
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_search_by_hashtag

scrapecreators-cli tiktok-search-by-hashtag

Argument	Required	Type	Details
`hashtag`	Yes	string	Hashtag to search for (without #)
`region`	No; body/guard rules apply	string	Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.
`cursor`	No; body/guard rules apply	number	Cursor to get more videos. Get 'cursor' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_search_by_keyword

scrapecreators-cli tiktok-search-by-keyword

Argument	Required	Type	Details
`query`	Yes	string	Keyword to search for
`date_posted`	No; body/guard rules apply	string	Time Frame Values: `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`.
`sort_by`	No; body/guard rules apply	string	Sort by Values: `relevance`, `most-liked`, `date-posted`.
`region`	No; body/guard rules apply	string	Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
`cursor`	No; body/guard rules apply	number	Cursor to get more videos. Get 'cursor' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_top_search

scrapecreators-cli tiktok-top-search

Argument	Required	Type	Details
`query`	Yes	string	Keyword to search for
`publish_time`	No; body/guard rules apply	string	Time Frame TikTok was posted Values: `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`.
`sort_by`	No; body/guard rules apply	string	Sort by Values: `relevance`, `most-liked`, `date-posted`.
`region`	No; body/guard rules apply	string	Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
`cursor`	No; body/guard rules apply	number	Cursor to get more videos. Get 'cursor' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_get_popular_creators

scrapecreators-cli tiktok-get-popular-creators

Argument	Required	Type	Details
`page`	No; body/guard rules apply	number	Page number
`sortBy`	No; body/guard rules apply	string	Sort creators by engagement, follower count, or average views Values: `engagement`, `follower`, `avg_views`.
`followerCount`	No; body/guard rules apply	string	Filter by follower count range Values: `10K-100K`, `100K-1M`, `1M-10M`, `10M+`.
`creatorCountry`	No; body/guard rules apply	string	Country code of the creator Values: `AU`, `BR`, `CA`, `EG`, `FR`, `DE`, `ID`, `IL`, `IT`, `JP`, `MY`, `PH`, `RU`, `SA`, `SG`, `KR`, `ES`, `TW`, `TH`, `TR`, `AE`, `GB`, `US`, `VN`.
`audienceCountry`	No; body/guard rules apply	string	Country code of the audience/follower Values: `AU`, `BR`, `CA`, `EG`, `FR`, `DE`, `ID`, `IL`, `IT`, `JP`, `MY`, `PH`, `RU`, `SA`, `SG`, `KR`, `ES`, `TW`, `TH`, `TR`, `AE`, `GB`, `US`, `VN`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_get_song_details

scrapecreators-cli tiktok-get-song-details

Argument	Required	Type	Details
`clipId`	Yes	string	This is a little confusing because this isn't songId like you'd think. It is the clipId. I guess because you can clip different portions of a song 🤷‍♂️
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_tiktoks_using_song

scrapecreators-cli tiktok-tiktoks-using-song

Argument	Required	Type	Details
`clipId`	No; body/guard rules apply	string	This is clipId. Can be found on a url like so: https://www.tiktok.com/music/That%27s-Who-I-Praise-7370375686554782506, where 7370375686554782506 is the clipId
`cursor`	No; body/guard rules apply	number	The cursor to get the next page of results.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli tiktok-trending-feed

Argument	Required	Type	Details
`region`	Yes	string	Where you want the proxy to be. This doesn't mean that you will only see TikToks from this region, you will just see the content that isn't banned in that region.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_shop_shop_search

scrapecreators-cli tiktok-shop-shop-search

Argument	Required	Type	Details
`query`	Yes	string	Term you want to search for
`page`	No; body/guard rules apply	number	Page number to retrieve
`region`	No; body/guard rules apply	string	Region to search shop products in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent results. Sorry for the inconvenience. Values: `US`, `GB`, `DE`, `FR`, `IT`, `ID`, `MY`, `MX`, `PH`, `SG`, `ES`, `TH`, `VN`, `BR`, `JP`, `IE`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_shop_shop_products

scrapecreators-cli tiktok-shop-shop-products

Argument	Required	Type	Details
`url`	Yes	string	The TikTok Shop store URL.
`cursor`	No; body/guard rules apply	string	Cursor parameter from the previous response to retrieve the next page of products. Omit for the first page.
`sort_by`	No; body/guard rules apply	string	Sort products by best-selling items (`top`) or newest products (`new_releases`). Defaults to `top`. Values: `top`, `new_releases`.
`region`	No; body/guard rules apply	string	Region to get shop products from. Defaults to US if not provided. Non-US regions are not reliable right now and may return `not_found` or limited catalog data even when the shop appears in search. Sorry for the inconvenience. Values: `US`, `GB`, `DE`, `FR`, `IT`, `ID`, `MY`, `MX`, `PH`, `SG`, `ES`, `TH`, `VN`, `BR`, `JP`, `IE`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_shop_product_details

scrapecreators-cli tiktok-shop-product-details

Argument	Required	Type	Details
`url`	Yes	string	The URL of the product to get details for.
`region`	No; body/guard rules apply	string	Region for the product details request. US is the reliable region right now; non-US regions should not be considered reliable and may return `bad_request` or missing product data. Sorry for the inconvenience.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_shop_product_reviews

scrapecreators-cli tiktok-shop-product-reviews

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	The URL of the product (required if product_id is not provided)
`product_id`	No; body/guard rules apply	string	The ID of the product (required if url is not provided)
`region`	No; body/guard rules apply	string	The region of the product. US is the reliable region right now; non-US regions should not be considered reliable and may return limited or inconsistent review data. Sorry for the inconvenience.
`page`	No; body/guard rules apply	number	The page number of the reviews
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_shop_user_showcase

scrapecreators-cli tiktok-shop-user-showcase

Argument	Required	Type	Details
`handle`	Yes	string	The handle of the user
`region`	No; body/guard rules apply	string	Region to put the proxy in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent showcase data. Sorry for the inconvenience.
`cursor`	No; body/guard rules apply	string	The cursor to the next page of products
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_profile

scrapecreators-cli instagram-profile

Argument	Required	Type	Details
`handle`	Yes	string	Instagram handle
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_basic_profile

scrapecreators-cli instagram-basic-profile

Argument	Required	Type	Details
`userId`	No; body/guard rules apply	string	Instagram user id
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_posts

scrapecreators-cli instagram-posts

Argument	Required	Type	Details
`handle`	Yes	string	Instagram handle
`next_max_id`	No; body/guard rules apply	string	Cursor to get next page of results.
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_user_tagged_posts

scrapecreators-cli instagram-user-tagged-posts

Argument	Required	Type	Details
`user_id`	Yes	string	Numeric Instagram user ID.
`cursor`	No; body/guard rules apply	string	Cursor returned by the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_reels

scrapecreators-cli instagram-reels

Argument	Required	Type	Details
`user_id`	No; body/guard rules apply	string	Instagram user id. Use this for faster response times.
`handle`	No; body/guard rules apply	string	Instagram handle. Use user_id for faster response times.
`max_id`	No; body/guard rules apply	string	Max id to get more reels. Get 'max_id' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_post_reel_info

scrapecreators-cli instagram-post-reel-info

Argument	Required	Type	Details
`url`	Yes	string	Instagram post or reel URL
`region`	No; body/guard rules apply	string	2 letter country code to set the proxy in
`trim`	No; body/guard rules apply	boolean	Set to true to get a trimmed response
`download_media`	No; body/guard rules apply	boolean	Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
`include_play_count`	No; body/guard rules apply	boolean	Set to false to omit `video_play_count` and skip its additional fetch for a faster response. Defaults to true.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_transcript

scrapecreators-cli instagram-transcript

Argument	Required	Type	Details
`url`	Yes	string	Instagram post or reel URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_search_instagram

scrapecreators-cli instagram-search-instagram

Argument	Required	Type	Details
`query`	Yes	string	The username, hashtag, place, or keyword to search for.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_popular_search

scrapecreators-cli instagram-popular-search

Argument	Required	Type	Details
`query`	Yes	string	The Popular topic to search for.
`cursor`	No; body/guard rules apply	string	The opaque cursor returned by the previous response. Use it with the same query to fetch the next page of posts.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_search_hashtag_posts

scrapecreators-cli instagram-search-hashtag-posts

Argument	Required	Type	Details
`hashtag`	Yes	string	The hashtag to search for. Include or omit the #.
`date_posted`	No; body/guard rules apply	string	Only return Google-indexed posts found in this relative window. Values: `last-hour`, `last-day`, `last-week`, `last-month`, `last-year`.
`media_type`	No; body/guard rules apply	string	Use all to search public posts and reels, or reels to only return reels. Defaults to all. Values: `all`, `reels`.
`cursor`	No; body/guard rules apply	string	The cursor returned by the previous response. It is the next Google results page number and cannot exceed 11; cursor 12 or greater returns a 400 response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_search_instagram_profiles

scrapecreators-cli instagram-search-instagram-profiles

Argument	Required	Type	Details
`query`	Yes	string	The profile name or username to search for.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_search_reels

scrapecreators-cli instagram-search-reels

Argument	Required	Type	Details
`query`	Yes	string	The keyword to search for
`date_posted`	No; body/guard rules apply	string	Google-indexed date window. Recent hour/day filters are not supported because Google does not index Instagram reels reliably enough in those windows. Values: `last-week`, `last-month`, `last-year`.
`page`	No; body/guard rules apply	number	The page number to return. Must be between 1 and 11; page 12 or greater returns a 400 response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_get_reels_by_audio_id

scrapecreators-cli instagram-get-reels-by-audio-id

Argument	Required	Type	Details
`audio_id`	Yes	string	The audio id from the Instagram audio page URL.
`cursor`	No; body/guard rules apply	string	Pagination cursor returned by Instagram from the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli instagram-trending-reels

Argument	Required	Type	Details
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_comments

scrapecreators-cli instagram-comments

Argument	Required	Type	Details
`url`	Yes	string	The URL of the post or reel to get comments from
`cursor`	No; body/guard rules apply	string	The cursor to get more comments. Get 'cursor' from previous response.
`include_replies`	No; body/guard rules apply	boolean	Set to true to include replies for every returned comment. This always costs 15 credits because each comment requires a separate Instagram replies request. You will still be charged 15 credits if no replies are returned. This is much slower and may time out at 29 seconds.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_comment_replies

scrapecreators-cli instagram-comment-replies

Argument	Required	Type	Details
`url`	Yes	string	The Instagram post or reel URL
`comment_id`	Yes	string	The parent comment ID from the Comments endpoint
`cursor`	No; body/guard rules apply	string	The cursor to get more replies. Get `cursor` from the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_story_highlights

scrapecreators-cli instagram-story-highlights

Argument	Required	Type	Details
`user_id`	No; body/guard rules apply	string	Instagram user id. Use for faster response times.
`handle`	No; body/guard rules apply	string	Instagram handle. Use user_id for faster response times.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_highlights_details

scrapecreators-cli instagram-highlights-details

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	The ID of the highlight to get details for
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_profile_post_count

scrapecreators-cli instagram-profile-post-count

Argument	Required	Type	Details
`handle`	Yes	string	Instagram handle
`allow_estimated`	No; body/guard rules apply	boolean	Set to true to return scaled estimates when Instagram abbreviates counts for profiles with more than 10,000 posts. Defaults to false; false or omitted returns an uncharged 422 when only an estimate is available.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

instagram_embed_html

scrapecreators-cli instagram-embed-html

Argument	Required	Type	Details
`handle`	Yes	string	Instagram handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

telegram_channel_details

scrapecreators-cli telegram-channel-details

Argument	Required	Type	Details
`handle`	Yes	string	Public Telegram handle, @handle, or t.me channel URL.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

telegram_channel_posts

scrapecreators-cli telegram-channel-posts

Argument	Required	Type	Details
`handle`	Yes	string	Public Telegram handle, @handle, or t.me channel URL.
`cursor`	No; body/guard rules apply	string	Numeric cursor returned by the previous page. Omit it for the latest posts.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

telegram_post_details

scrapecreators-cli telegram-post-details

Argument	Required	Type	Details
`url`	Yes	string	Public Telegram post URL.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_details

scrapecreators-cli youtube-channel-details

Argument	Required	Type	Details
`channelId`	No; body/guard rules apply	string	YouTube channel ID. Can pass a channelId, handle or url
`handle`	No; body/guard rules apply	string	YouTube channel handle. Can pass a channelId, handle or url
`url`	No; body/guard rules apply	string	YouTube channel URL. Can pass a channelId, handle or url
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_videos

scrapecreators-cli youtube-channel-videos

Argument	Required	Type	Details
`channelId`	No; body/guard rules apply	string	YouTube channel ID
`handle`	No; body/guard rules apply	string	YouTube channel handle
`sort`	No; body/guard rules apply	string	Sort by latest or popular Values: `latest`, `popular`.
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more videos. Get 'continuationToken' from previous response.
`is_paid_promotions`	No; body/guard rules apply	string	Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement search surface. This returns normal YouTube videos where the creator declared paid promotion. Cannot be combined with filter, uploadDate, sortBy, type, duration, or includeExtras.
`includeExtras`	No; body/guard rules apply	string	This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. Honestly, if you use this param, the error rate is higher. We might deprecate this param in the future.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_playlists

scrapecreators-cli youtube-channel-playlists

Argument	Required	Type	Details
`channelId`	No; body/guard rules apply	string	YouTube channel ID
`handle`	No; body/guard rules apply	string	YouTube channel handle
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more playlists. Get 'continuationToken' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_lives

scrapecreators-cli youtube-channel-lives

Argument	Required	Type	Details
`channelId`	No; body/guard rules apply	string	YouTube channel ID
`handle`	No; body/guard rules apply	string	YouTube channel handle
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more lives. Get 'continuationToken' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_community_posts

scrapecreators-cli youtube-channel-community-posts

Argument	Required	Type	Details
`channelId`	No; body/guard rules apply	string	YouTube channel ID
`handle`	No; body/guard rules apply	string	YouTube channel handle
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more community posts. Get 'continuationToken' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_channel_shorts

scrapecreators-cli youtube-channel-shorts

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Can pass channelId or handle
`channelId`	No; body/guard rules apply	string	Can pass channelId or handle
`sort`	No; body/guard rules apply	string	Sort by newest or popular Values: `newest`, `popular`.
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more videos. Get 'continuationToken' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_video_short_details

scrapecreators-cli youtube-video-short-details

Argument	Required	Type	Details
`url`	Yes	string	YouTube video or short URL
`language`	No; body/guard rules apply	string	Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_transcript

scrapecreators-cli youtube-transcript

Argument	Required	Type	Details
`url`	Yes	string	YouTube video or short URL
`language`	No; body/guard rules apply	string	Language code, ie 'en', 'es', 'fr' or 'en-US'. Overrides the default track selection unless original_audio=true. If omitted, prefers captions matching the original spoken language when YouTube identifies the original audio. If that metadata is unavailable or ambiguous, prefers an auto-generated caption, otherwise the first caption track. If the requested or identified original language has no matching captions, the transcript will be null and no credits are charged.
`original_audio`	No; body/guard rules apply	boolean	Set to true to return captions only in the original spoken language identified by YouTube. Takes precedence over language. If the original audio cannot be reliably identified or has no matching captions, transcript, transcript_only_text, and language are null and no credits are charged. No extra lookup or credit cost; a returned transcript costs the usual 1 credit. Omit or set to false for the existing default selection.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_video_sponsors

scrapecreators-cli youtube-video-sponsors

Argument	Required	Type	Details
`url`	Yes	string	YouTube video or short URL
`language`	No; body/guard rules apply	string	2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_search

scrapecreators-cli youtube-search

Argument	Required	Type	Details
`query`	Yes	string	Search query. For stricter title matching, use YouTube's intitle: operator, for example intitle:"Foursquare Swarm". Quoted queries by themselves may still be broadened by YouTube when no fresh exact matches are available.
`uploadDate`	No; body/guard rules apply	string	Upload date Values: `today`, `this_week`, `this_month`, `this_year`.
`sortBy`	No; body/guard rules apply	string	Sort by Values: `relevance`, `popular`.
`type`	No; body/guard rules apply	string	Type of content to search for Values: `videos`, `shorts`, `channels`, `playlists`.
`duration`	No; body/guard rules apply	string	Duration of the video. Only applies to videos (not shorts). Values: `under_3_min`, `between_3_and_20_min`, `over_20_min`.
`region`	No; body/guard rules apply	string	2 letter country code of the country to put the proxy in.
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more videos. Get 'continuationToken' from previous response.
`includeExtras`	No; body/guard rules apply	string	This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_search_typeahead

scrapecreators-cli youtube-search-typeahead

Argument	Required	Type	Details
`query`	Yes	string	Partial or complete YouTube search query
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_search_by_hashtag

scrapecreators-cli youtube-search-by-hashtag

Argument	Required	Type	Details
`hashtag`	Yes	string	Hashtag to search for
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more videos. Get 'continuationToken' from previous response.
`type`	No; body/guard rules apply	string	Search for all types of content or only shorts Values: `all`, `shorts`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_comments

scrapecreators-cli youtube-comments

Argument	Required	Type	Details
`url`	Yes	string	YouTube video URL
`continuationToken`	No; body/guard rules apply	string	Continuation token to get more comments. Get 'continuationToken' from previous response.
`order`	No; body/guard rules apply	string	Order of comments Values: `top`, `newest`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_comment_replies

scrapecreators-cli youtube-comment-replies

Argument	Required	Type	Details
`continuationToken`	Yes	string	Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli youtube-trending-shorts

Argument	Required	Type	Details
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_playlist

scrapecreators-cli youtube-playlist

Argument	Required	Type	Details
`playlist_id`	Yes	string	The ID of the YouTube playlist. In the YouTube URL it will be the 'list' parameter.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

youtube_community_post_details

scrapecreators-cli youtube-community-post-details

Argument	Required	Type	Details
`url`	Yes	string	The URL of the YouTube community post to get
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

rumble_search

scrapecreators-cli rumble-search

Argument	Required	Type	Details
`query`	Yes	string	Search query.
`cursor`	No; body/guard rules apply	string	Cursor from the previous response. This is the next page number, like 2 or 3.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

rumble_channel_videos

scrapecreators-cli rumble-channel-videos

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Rumble channel handle. If you'd prefer to use the URL instead, use the url parameter.
`url`	No; body/guard rules apply	string	Rumble channel URL. If you'd prefer to use the handle instead, use the handle parameter.
`cursor`	No; body/guard rules apply	string	Cursor from the previous response. This is the next page number, like 2 or 3.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

rumble_video

scrapecreators-cli rumble-video

Argument	Required	Type	Details
`url`	Yes	string	Rumble video URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

rumble_transcript

scrapecreators-cli rumble-transcript

Argument	Required	Type	Details
`url`	Yes	string	Rumble video URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

rumble_comments

scrapecreators-cli rumble-comments

Argument	Required	Type	Details
`url`	Yes	string	Rumble video URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_person_profile

scrapecreators-cli linkedin-person-profile

Argument	Required	Type	Details
`url`	Yes	string	The URL of the LinkedIn profile to get
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_company_page

scrapecreators-cli linkedin-company-page

Argument	Required	Type	Details
`url`	Yes	string	The URL of the LinkedIn company page to get
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_company_posts

scrapecreators-cli linkedin-company-posts

Argument	Required	Type	Details
`url`	Yes	string	The URL of the LinkedIn company page to get
`page`	No; body/guard rules apply	number	The page number to get
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_search_posts

scrapecreators-cli linkedin-search-posts

Argument	Required	Type	Details
`query`	Yes	string	Keyword or phrase to search for in public LinkedIn posts
`date_posted`	No; body/guard rules apply	string	Date posted filter based on Google-indexed results Values: `last-hour`, `last-day`, `last-week`, `last-month`, `last-year`.
`cursor`	No; body/guard rules apply	string	The cursor returned from the previous response. The maximum cursor is 11; cursor 12 or greater returns a 400 response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_post

scrapecreators-cli linkedin-post

Argument	Required	Type	Details
`url`	Yes	string	The URL of the LinkedIn post to get
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_post_transcript

scrapecreators-cli linkedin-post-transcript

Argument	Required	Type	Details
`url`	Yes	string	The URL of the LinkedIn post to get the transcript from
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_profile

scrapecreators-cli facebook-profile

Argument	Required	Type	Details
`url`	Yes	string	Facebook profile URL
`get_business_hours`	No; body/guard rules apply	string	Get the business's hours
`include_gated_profile`	No; body/guard rules apply	string	When true, returns limited public fields for gated or age-restricted profiles. Ignored for normal public profiles — those still return the full response.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_profile_reels

scrapecreators-cli facebook-profile-reels

Argument	Required	Type	Details
`url`	Yes	string	Facebook page URL
`next_page_id`	No; body/guard rules apply	string	To paginate through to the next page
`cursor`	No; body/guard rules apply	string	To paginate through to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_profile_photos

scrapecreators-cli facebook-profile-photos

Argument	Required	Type	Details
`url`	Yes	string	Facebook page URL
`next_page_id`	No; body/guard rules apply	string	To paginate through to the next page
`cursor`	No; body/guard rules apply	string	To paginate through to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_profile_posts

scrapecreators-cli facebook-profile-posts

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	Facebook profile URL
`pageId`	No; body/guard rules apply	string	Facebook profile page id
`cursor`	No; body/guard rules apply	string	To paginate through the posts
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_profile_events

scrapecreators-cli facebook-profile-events

Argument	Required	Type	Details
`url`	Yes	string	The URL of the public Facebook page
`cursor`	No; body/guard rules apply	string	The cursor to paginate to get more events
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_post

scrapecreators-cli facebook-post

Argument	Required	Type	Details
`url`	Yes	string	The URL of the post to get
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_transcript

scrapecreators-cli facebook-transcript

Argument	Required	Type	Details
`url`	Yes	string	Facebook post URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_comments

scrapecreators-cli facebook-comments

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	Facebook post URL (or reel URL)
`feedback_id`	No; body/guard rules apply	string	Using feedback_id (instead of url) will really speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post.
`cursor`	No; body/guard rules apply	string	Cursor to get more comments. Get 'cursor' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_comment_replies

scrapecreators-cli facebook-comment-replies

Argument	Required	Type	Details
`feedback_id`	Yes	string	The feedback_id of the comment. Be careful, this is not the comment id. You can get the feedback_id from the /v1/facebook/post/comments endpoint.
`expansion_token`	Yes	string	The expansion_token of the comment. You can get the expansion_token from the /v1/facebook/post/comments endpoint.
`cursor`	No; body/guard rules apply	string	The cursor to paginate to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_facebook_group_info

scrapecreators-cli facebook-facebook-group-info

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	The Facebook group URL. Group sub-page URLs such as /about work too.
`group_id`	No; body/guard rules apply	string	The numeric Facebook group ID. Provide this instead of url if you already have it.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_facebook_group_posts

scrapecreators-cli facebook-facebook-group-posts

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	The URL of the group
`group_id`	No; body/guard rules apply	string	The ID of the group
`sort_by`	No; body/guard rules apply	string	How to sort the posts. Defaults to CHRONOLOGICAL. Values: `TOP_POSTS`, `RECENT_ACTIVITY`, `CHRONOLOGICAL`, `CHRONOLOGICAL_LISTINGS`.
`cursor`	No; body/guard rules apply	string	The cursor to paginate to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_user

scrapecreators-cli github-user

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub username/handle of the user you want the details for
`url`	No; body/guard rules apply	string	GitHub user URL, e.g. https://github.com/torvalds.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_repositories

scrapecreators-cli github-repositories

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub username/handle of the user you want the repositories for
`url`	No; body/guard rules apply	string	GitHub user URL, e.g. https://github.com/kentcdodds.
`type`	No; body/guard rules apply	string	Repository type. Defaults to owner. GitHub also supports all and member. Values: `owner`, `all`, `member`.
`sort`	No; body/guard rules apply	string	Sort by created, updated, pushed, or full_name. Defaults to updated. Values: `created`, `updated`, `pushed`, `full_name`.
`direction`	No; body/guard rules apply	string	Sort direction: ascending or descending. Values: `asc`, `desc`.
`cursor`	No; body/guard rules apply	number	Cursor from the previous response. Defaults to 1.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_pull_requests

scrapecreators-cli github-pull-requests

Argument	Required	Type	Details
`handle`	Yes	string	GitHub username/handle of the user you want pull requests for
`since`	No; body/guard rules apply	string	Only return pull requests created on or after this date. Use YYYY-MM-DD.
`until`	No; body/guard rules apply	string	Only return pull requests created on or before this date. Use YYYY-MM-DD.
`cursor`	No; body/guard rules apply	number	Cursor from the previous response. Defaults to 1.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_activity

scrapecreators-cli github-activity

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub handle
`url`	No; body/guard rules apply	string	GitHub user URL, e.g. https://github.com/kentcdodds.
`year`	No; body/guard rules apply	number	When provided, returns profile contribution activity for that year. Defaults to the current year.
`cursor`	No; body/guard rules apply	number	Cursor from the previous response. Pages backward by month through the selected year.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_followers

scrapecreators-cli github-followers

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub username/handle of the user you want the followers for
`url`	No; body/guard rules apply	string	GitHub user URL, e.g. https://github.com/torvalds.
`cursor`	No; body/guard rules apply	number	Cursor from the previous response. Defaults to 1.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_following

scrapecreators-cli github-following

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub handle
`url`	No; body/guard rules apply	string	GitHub profile URL
`cursor`	No; body/guard rules apply	number	Cursor from the previous response. Defaults to 1.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_contributions

scrapecreators-cli github-contributions

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	GitHub handle
`url`	No; body/guard rules apply	string	GitHub profile URL
`year`	No; body/guard rules apply	number	Contribution graph year. Defaults to the current year.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

github_repository

scrapecreators-cli github-repository

Argument	Required	Type	Details
`url`	Yes	string	GitHub repository URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli github-trending-repositories

Argument	Required	Type	Details
`language`	No; body/guard rules apply	string	Optional coding language, e.g. javascript, python, or go.
`since`	No; body/guard rules apply	string	Trending range: daily, weekly, or monthly. Defaults to daily. Values: `daily`, `weekly`, `monthly`.
`spoken_language_code`	No; body/guard rules apply	string	Optional spoken language code filter, e.g. en.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli github-trending-developers

Argument	Required	Type	Details
`language`	No; body/guard rules apply	string	Optional trending coding language, e.g. javascript, python, or go.
`since`	No; body/guard rules apply	string	Trending range: daily, weekly, or monthly. Defaults to daily. Values: `daily`, `weekly`, `monthly`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_marketplace_marketplace_location_search

scrapecreators-cli facebook-marketplace-marketplace-location-search

Argument	Required	Type	Details
`query`	Yes	string	Location search query
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_marketplace_marketplace_search

scrapecreators-cli facebook-marketplace-marketplace-search

Argument	Required	Type	Details
`query`	Yes	string	Search keyword
`category_id`	No; body/guard rules apply	string	Numeric Facebook Marketplace category ID. Listing results include this value as category_id.
`lat`	Yes	number	Latitude for the search location
`lng`	Yes	number	Longitude for the search location
`radius_km`	No; body/guard rules apply	number	Search radius in kilometers
`min_price`	No; body/guard rules apply	number	Minimum listing price
`max_price`	No; body/guard rules apply	number	Maximum listing price
`sort_by`	No; body/guard rules apply	string	Facebook Marketplace sort option. creation_time_descend usually orders the first pages newest first, but Facebook can insert newer listings on later cursor pages. Values: `suggested`, `distance_ascend`, `creation_time_descend`, `price_ascend`, `price_descend`.
`delivery_method`	No; body/guard rules apply	string	Delivery filter Values: `all`, `local_pickup`, `shipping`.
`condition`	No; body/guard rules apply	string	Condition filter Values: `new`, `used_like_new`, `used_good`, `used_fair`.
`date_listed`	No; body/guard rules apply	string	Facebook Marketplace date filter. Uses the same calendar-day buckets as the UI, so last_24_hours can include listings from the prior calendar day. Values: `all`, `1`, `7`, `30`, `last_24_hours`, `last_7_days`, `last_30_days`.
`availability`	No; body/guard rules apply	string	Availability filter Values: `available`, `sold`, `all`.
`cursor`	No; body/guard rules apply	string	Opaque pagination cursor returned from the previous response. Pass it back as-is.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_marketplace_marketplace_item

scrapecreators-cli facebook-marketplace-marketplace-item

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Facebook Marketplace item id
`url`	No; body/guard rules apply	string	Facebook Marketplace item URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_events_search_events

scrapecreators-cli facebook-events-search-events

Argument	Required	Type	Details
`query`	Yes	string	The query to search for
`cursor`	No; body/guard rules apply	string	The cursor to paginate to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_events_events

scrapecreators-cli facebook-events-events

Argument	Required	Type	Details
`url`	Yes	string	The URL of the city's Facebook Events page
`time`	No; body/guard rules apply	string	The time frame to search for. Defaults to all time Values: `today`, `this_week`, `next_week`.
`cursor`	No; body/guard rules apply	string	The cursor to paginate to the next page
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_events_event_details

scrapecreators-cli facebook-events-event-details

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	The ID of the event
`url`	No; body/guard rules apply	string	The URL of the event
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_ad_library_ad_details

scrapecreators-cli facebook-ad-library-ad-details

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Facebook Ad Id
`url`	No; body/guard rules apply	string	Facebook Ad URL
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_ad_library_ad_transcript

scrapecreators-cli facebook-ad-library-ad-transcript

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Facebook Ad Id
`url`	No; body/guard rules apply	string	Facebook Ad URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_ad_library_search

scrapecreators-cli facebook-ad-library-search

Argument	Required	Type	Details
`query`	Yes	string	Keyword to search for
`sort_by`	No; body/guard rules apply	string	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. Values: `total_impressions`, `relevancy_monthly_grouped`.
`search_type`	No; body/guard rules apply	string	If you want to search by exact phrase or not Values: `keyword_unordered`, `keyword_exact_phrase`.
`ad_type`	No; body/guard rules apply	string	Search for all ads or only political and issue ads Values: `all`, `political_and_issue_ads`.
`country`	No; body/guard rules apply	string	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`language`	No; body/guard rules apply	string	Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.
`status`	No; body/guard rules apply	string	Status of the ad. Defaults to ACTIVE. Values: `ALL`, `ACTIVE`, `INACTIVE`.
`media_type`	No; body/guard rules apply	string	Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. Values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`.
`start_date`	No; body/guard rules apply	string	Impressions start date. Needs to be in YYYY-MM-DD format.
`end_date`	No; body/guard rules apply	string	Impressions end date. Needs to be in YYYY-MM-DD format.
`cursor`	No; body/guard rules apply	string	Cursor to paginate through results
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

facebook_ad_library_search_post

scrapecreators-cli facebook-ad-library-search-post

Argument	Required	Type	Details
`query`	No; body/guard rules apply	string	Keyword to search for
`sort_by`	No; body/guard rules apply	string	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. Values: `total_impressions`, `relevancy_monthly_grouped`.
`search_type`	No; body/guard rules apply	string	If you want to search by exact phrase or not Values: `keyword_unordered`, `keyword_exact_phrase`.
`ad_type`	No; body/guard rules apply	string	Search for all ads or only political and issue ads Values: `all`, `political_and_issue_ads`.
`country`	No; body/guard rules apply	string	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`language`	No; body/guard rules apply	string	Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.
`status`	No; body/guard rules apply	string	Status of the ad. Defaults to ACTIVE. Values: `ALL`, `ACTIVE`, `INACTIVE`.
`media_type`	No; body/guard rules apply	string	Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. Values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`.
`start_date`	No; body/guard rules apply	string	Impressions start date. Needs to be in YYYY-MM-DD format.
`end_date`	No; body/guard rules apply	string	Impressions end date. Needs to be in YYYY-MM-DD format.
`cursor`	No; body/guard rules apply	string	Cursor to paginate through results
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.
`payload`	No; body/guard rules apply	object	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`payload_file`	No; body/guard rules apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

A JSON body is required; body flags, payload or payload_file are alternatives. Body requires: query.

facebook_ad_library_company_ads

scrapecreators-cli facebook-ad-library-company-ads

Argument	Required	Type	Details
`pageId`	No; body/guard rules apply	string	The companies ad library page id. You can get this with my Search For Companies Endpoint. Can either use this or companyName
`companyName`	No; body/guard rules apply	string	The name of the company. Can either use this or pageId
`country`	No; body/guard rules apply	string	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`status`	No; body/guard rules apply	string	Status of the ad. Defaults to ACTIVE. Values: `ALL`, `ACTIVE`, `INACTIVE`.
`media_type`	No; body/guard rules apply	string	Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme. Values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`.
`language`	No; body/guard rules apply	string	Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
`sort_by`	No; body/guard rules apply	string	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. Values: `total_impressions`, `relevancy_monthly_grouped`.
`start_date`	No; body/guard rules apply	string	Start date to search for. Format: YYYY-MM-DD
`end_date`	No; body/guard rules apply	string	End date to search for. Format: YYYY-MM-DD
`cursor`	No; body/guard rules apply	string	Cursor to paginate through results
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

Provide pageId or companyName in the applicable query/body; an empty selector is rejected locally.

facebook_ad_library_company_ads_post

scrapecreators-cli facebook-ad-library-company-ads-post

Argument	Required	Type	Details
`pageId`	No; body/guard rules apply	string	The companies ad library page id. You can get this with my Search For Companies Endpoint. Can either use this or companyName
`companyName`	No; body/guard rules apply	string	The name of the company. Can either use this or pageId
`country`	No; body/guard rules apply	string	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`status`	No; body/guard rules apply	string	Status of the ad. Defaults to ACTIVE. Values: `ALL`, `ACTIVE`, `INACTIVE`.
`media_type`	No; body/guard rules apply	string	Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme. Values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`.
`language`	No; body/guard rules apply	string	Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
`sort_by`	No; body/guard rules apply	string	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. Values: `total_impressions`, `relevancy_monthly_grouped`.
`start_date`	No; body/guard rules apply	string	Start date to search for. Format: YYYY-MM-DD
`end_date`	No; body/guard rules apply	string	End date to search for. Format: YYYY-MM-DD
`cursor`	No; body/guard rules apply	string	Cursor to paginate through results
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.
`payload`	No; body/guard rules apply	object	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`payload_file`	No; body/guard rules apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

A JSON body is required; body flags, payload or payload_file are alternatives. Body requires: .

Provide pageId or companyName in the applicable query/body; an empty selector is rejected locally.

facebook_ad_library_search_for_companies

scrapecreators-cli facebook-ad-library-search-for-companies

Argument	Required	Type	Details
`query`	Yes	string	Keyword to search for
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_ad_library_ad_library_search

scrapecreators-cli tiktok-ad-library-ad-library-search

Argument	Required	Type	Details
`query`	No; body/guard rules apply	string	General ad search. Provide either query or advertiser_name, not both.
`advertiser_name`	No; body/guard rules apply	string	Advertiser name to resolve through TikTok's typeahead and search by advertiser entity. Falls back to TikTok's name search when no entity matches. Provide either advertiser_name or query, not both.
`adv_biz_ids`	No; body/guard rules apply	string	TikTok advertiser business ID from a See all ads link. Use it with advertiser_name to pin the exact advertiser. Required companion: advertiser_name; ID-only searches return 400 because TikTok ignores the ID without the name.
`cursor`	No; body/guard rules apply	string	Opaque cursor returned from the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

tiktok_ad_library_ad_library_ad

scrapecreators-cli tiktok-ad-library-ad-library-ad

Argument	Required	Type	Details
`ad_id`	Yes	string	Creative Center Top Ads material ID or URL, or a public Ads Library ad ID or library.tiktok.com detail URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

google_ad_library_company_ads

scrapecreators-cli google-ad-library-company-ads

Argument	Required	Type	Details
`domain`	No; body/guard rules apply	string	The domain of the company
`advertiser_id`	No; body/guard rules apply	string	The advertiser id of the company
`topic`	No; body/guard rules apply	string	The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU' Values: `all`, `political`.
`region`	No; body/guard rules apply	string	The region to search for. Defaults to anywhere
`start_date`	No; body/guard rules apply	string	Start date to search for. Format: YYYY-MM-DD
`end_date`	No; body/guard rules apply	string	End date to search for. Format: YYYY-MM-DD
`platform`	No; body/guard rules apply	string	Platform to search for. Values: `google_maps`, `google_play`, `google_search`, `google_shopping`, `youtube`.
`format`	No; body/guard rules apply	string	Ad format to search for. Values: `text`, `image`, `video`.
`get_ad_details`	No; body/guard rules apply	string	Set to true to get the ad details. Will cost 25 credits.
`cursor`	No; body/guard rules apply	string	Cursor to paginate through results
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

google_ad_library_ad_details

scrapecreators-cli google-ad-library-ad-details

Argument	Required	Type	Details
`url`	Yes	string	The url of the ad
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

google_ad_library_advertiser_search

scrapecreators-cli google-ad-library-advertiser-search

Argument	Required	Type	Details
`query`	Yes	string	The query to search for
`region`	No; body/guard rules apply	string	2-letter country code to search in. Defaults to US when omitted.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_ad_library_search_ads

scrapecreators-cli linkedin-ad-library-search-ads

Argument	Required	Type	Details
`company`	No; body/guard rules apply	string	The company name to search for. 'Microsoft' for example
`keyword`	No; body/guard rules apply	string	The keyword to search for
`companyId`	No; body/guard rules apply	string	The company id to search for
`countries`	No; body/guard rules apply	string	Comma separated list of countries. Example: US,CA,MX
`startDate`	No; body/guard rules apply	string	Start date in YYYY-MM-DD format. Must be used with endDate and cannot be earlier than the date one year ago.
`endDate`	No; body/guard rules apply	string	End date in YYYY-MM-DD format. Must be used with startDate and cannot be today or a future date.
`paginationToken`	No; body/guard rules apply	string	Pagination token to paginate through results
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkedin_ad_library_ad_details

scrapecreators-cli linkedin-ad-library-ad-details

Argument	Required	Type	Details
`url`	Yes	string	The url of the ad
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_profile

scrapecreators-cli twitter-profile

Argument	Required	Type	Details
`handle`	Yes	string	Twitter handle
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_user_tweets

scrapecreators-cli twitter-user-tweets

Argument	Required	Type	Details
`handle`	Yes	string	Twitter handle
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_tweet_details

scrapecreators-cli twitter-tweet-details

Argument	Required	Type	Details
`url`	Yes	string	Tweet URL
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_transcript

scrapecreators-cli twitter-transcript

Argument	Required	Type	Details
`url`	Yes	string	Tweet URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_community

scrapecreators-cli twitter-community

Argument	Required	Type	Details
`url`	Yes	string	Community URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitter_community_tweets

scrapecreators-cli twitter-community-tweets

Argument	Required	Type	Details
`url`	Yes	string	Community URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_subreddit_details

scrapecreators-cli reddit-subreddit-details

Argument	Required	Type	Details
`subreddit`	No; body/guard rules apply	string	Subreddit name. MUST be case sensitive. So 'AskReddit' not 'askreddit'.
`url`	No; body/guard rules apply	string	Subreddit URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_subreddit_posts

scrapecreators-cli reddit-subreddit-posts

Argument	Required	Type	Details
`subreddit`	Yes	string	Subreddit name
`timeframe`	No; body/guard rules apply	string	Timeframe to get posts from Values: `all`, `day`, `week`, `month`, `year`.
`sort`	No; body/guard rules apply	string	Sort order Values: `best`, `hot`, `new`, `top`, `rising`.
`after`	No; body/guard rules apply	string	After to get more posts. Get 'after' from previous response.
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_subreddit_search

scrapecreators-cli reddit-subreddit-search

Argument	Required	Type	Details
`subreddit`	Yes	string	Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL)
`query`	No; body/guard rules apply	string	Search query to find matching content
`sort`	No; body/guard rules apply	string	Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new Values: `relevance`, `hot`, `top`, `new`, `comments`.
`timeframe`	No; body/guard rules apply	string	Timeframe to filter results Values: `all`, `year`, `month`, `week`, `day`, `hour`.
`cursor`	No; body/guard rules apply	string	Cursor to get more results. Get 'cursor' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_post

scrapecreators-cli reddit-post

Argument	Required	Type	Details
`url`	Yes	string	Reddit post URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_post_comments

scrapecreators-cli reddit-post-comments

Argument	Required	Type	Details
`url`	Yes	string	Reddit post URL
`cursor`	No; body/guard rules apply	string	One opaque cursor returned by the previous response to get more comments or replies. Do not combine multiple cursors.
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_post_comments_post

scrapecreators-cli reddit-post-comments-post

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	Reddit post URL
`cursor`	No; body/guard rules apply	string	One opaque cursor returned by the previous response to get more comments or replies. Do not combine multiple cursors.
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.
`payload`	No; body/guard rules apply	object	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`payload_file`	No; body/guard rules apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

A JSON body is required; body flags, payload or payload_file are alternatives. Body requires: url.

reddit_post_transcript

scrapecreators-cli reddit-post-transcript

Argument	Required	Type	Details
`url`	Yes	string	Reddit post URL or direct v.redd.it video URL
`language`	No; body/guard rules apply	string	2 letter language code. Defaults to en.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

reddit_search

scrapecreators-cli reddit-search

Argument	Required	Type	Details
`query`	Yes	string	Search query
`filter`	No; body/guard rules apply	string	Search posts or comments Values: `posts`, `comments`.
`sort`	No; body/guard rules apply	string	Sort by. Comment search supports relevance, new, and top; comment_count is for post search only. Values: `relevance`, `new`, `top`, `comment_count`.
`timeframe`	No; body/guard rules apply	string	Post search timeframe Values: `all`, `day`, `week`, `month`, `year`.
`after`	No; body/guard rules apply	string	Used to paginate to next page
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli truth-social-profile

Argument	Required	Type	Details
`handle`	Yes	string	Truth Social username
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli truth-social-user-posts

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Truth Social username
`user_id`	No; body/guard rules apply	string	Truth Social user id. Use this for faster response times. Trumps is 107780257626128497. It is the 'id' field in the profile endpoint.
`next_max_id`	No; body/guard rules apply	string	Used to paginate to next page
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli truth-social-post

Argument	Required	Type	Details
`url`	Yes	string	Truth Social post URL
`download_media`	No; body/guard rules apply	boolean	Set to true to download the attached video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

threads_profile

scrapecreators-cli threads-profile

Argument	Required	Type	Details
`handle`	Yes	string	Threads username
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

threads_posts

scrapecreators-cli threads-posts

Argument	Required	Type	Details
`handle`	Yes	string	Threads username
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

threads_post

scrapecreators-cli threads-post

Argument	Required	Type	Details
`url`	Yes	string	The URL of the post to get
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

threads_search_by_keyword

scrapecreators-cli threads-search-by-keyword

Argument	Required	Type	Details
`query`	Yes	string	Keyword to search for
`start_date`	No; body/guard rules apply	string	Start date to search for
`end_date`	No; body/guard rules apply	string	End date to search for
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

threads_search_users

scrapecreators-cli threads-search-users

Argument	Required	Type	Details
`query`	Yes	string	Username to search for
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

bluesky_profile

scrapecreators-cli bluesky-profile

Argument	Required	Type	Details
`handle`	Yes	string	Bluesky handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

bluesky_posts

scrapecreators-cli bluesky-posts

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Bluesky handle
`user_id`	No; body/guard rules apply	string	Bluesky 'did'. (For some reason Bluesky calls their user ids, 'did' for whatever reason)
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

bluesky_post

scrapecreators-cli bluesky-post

Argument	Required	Type	Details
`url`	Yes	string	Bluesky post URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

pinterest_search

scrapecreators-cli pinterest-search

Argument	Required	Type	Details
`query`	Yes	string	Search query
`cursor`	No; body/guard rules apply	string	Cursor
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

pinterest_pin

scrapecreators-cli pinterest-pin

Argument	Required	Type	Details
`url`	Yes	string	Pinterest pin URL
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

pinterest_user_boards

scrapecreators-cli pinterest-user-boards

Argument	Required	Type	Details
`handle`	Yes	string	The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/)
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

pinterest_board

scrapecreators-cli pinterest-board

Argument	Required	Type	Details
`url`	Yes	string	The URL of the board to get
`cursor`	No; body/guard rules apply	string	The cursor to get the next page of results
`trim`	No; body/guard rules apply	boolean	Set to true for a trimmed down version of the response
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

google_search

scrapecreators-cli google-search

Argument	Required	Type	Details
`query`	Yes	string	Search query
`region`	No; body/guard rules apply	string	2 letter country code, ie US, UK, CA, etc This will show results from that country
`date_posted`	No; body/guard rules apply	string	Date posted Values: `last-hour`, `last-day`, `last-week`, `last-month`, `last-year`.
`page`	No; body/guard rules apply	number	Page number to retrieve. Must be between 1 and 11; page 12 or greater returns a 400 response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitch_profile

scrapecreators-cli twitch-profile

Argument	Required	Type	Details
`handle`	Yes	string	Twitch handle
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitch_user_videos

scrapecreators-cli twitch-user-videos

Argument	Required	Type	Details
`handle`	Yes	string	Twitch handle
`filter_by`	No; body/guard rules apply	string	Filter by Values: `HIGHLIGHT`, `ARCHIVE`, `UPLOAD`.
`sort_by`	No; body/guard rules apply	string	Sort by Values: `TIME`, `VIEWS`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitch_user_schedule

scrapecreators-cli twitch-user-schedule

Argument	Required	Type	Details
`handle`	Yes	string	Twitch handle
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitch_clip_transcript

scrapecreators-cli twitch-clip-transcript

Argument	Required	Type	Details
`url`	Yes	string	Twitch clip URL
`use_ai_as_fallback`	No; body/guard rules apply	boolean	Use AI transcription only when native captions are unavailable. Costs 10 credits when an AI transcript is returned. Defaults to false.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

twitch_clip

scrapecreators-cli twitch-clip

Argument	Required	Type	Details
`url`	Yes	string	Twitch clip URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

apple_music_artist

scrapecreators-cli apple-music-artist

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Apple Music artist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Apple Music artist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

apple_music_album

scrapecreators-cli apple-music-album

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Apple Music album id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Apple Music album URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

apple_music_track

scrapecreators-cli apple-music-track

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Apple Music song id. Some songs have standalone song URLs; for album tracks, use the url parameter.
`url`	No; body/guard rules apply	string	Apple Music song URL or album track URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

apple_music_search

scrapecreators-cli apple-music-search

Argument	Required	Type	Details
`query`	Yes	string	Search query
`type`	No; body/guard rules apply	string	Result type to return. Use all, song, album, artist, playlist, station, music_video, or radio_episode.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_artist

scrapecreators-cli spotify-artist

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify artist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify artist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_track

scrapecreators-cli spotify-track

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify track id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify song URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_album

scrapecreators-cli spotify-album

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify album id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify album URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_playlist

scrapecreators-cli spotify-playlist

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify playlist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify playlist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`cursor`	No; body/guard rules apply	string	Cursor returned by the previous response. Omit it for the first page.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_search

scrapecreators-cli spotify-search

Argument	Required	Type	Details
`query`	Yes	string	Search query
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_podcast

scrapecreators-cli spotify-podcast

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify podcast id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify podcast URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

spotify_podcast_episodes

scrapecreators-cli spotify-podcast-episodes

Argument	Required	Type	Details
`id`	No; body/guard rules apply	string	Spotify podcast id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	Spotify podcast URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`cursor`	No; body/guard rules apply	number	Cursor returned by the previous response. Omit for the first page.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

soundcloud_artist

scrapecreators-cli soundcloud-artist

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	SoundCloud artist handle. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	SoundCloud artist URL. If you'd prefer to use the handle instead, you can use the handle parameter instead.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

soundcloud_artist_tracks

scrapecreators-cli soundcloud-artist-tracks

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	SoundCloud artist handle. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No; body/guard rules apply	string	SoundCloud artist tracks URL. If you'd prefer to use the handle instead, you can use the handle parameter instead.
`cursor`	No; body/guard rules apply	string	Cursor to get more tracks. Get 'cursor' from previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

soundcloud_track

scrapecreators-cli soundcloud-track

Argument	Required	Type	Details
`url`	Yes	string	SoundCloud track URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

kwai_profile

scrapecreators-cli kwai-profile

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Kwai profile handle. Use this or url.
`url`	No; body/guard rules apply	string	Kwai profile URL. Use this or handle.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

kwai_user_posts

scrapecreators-cli kwai-user-posts

Argument	Required	Type	Details
`handle`	No; body/guard rules apply	string	Kwai profile handle. Use this or url.
`url`	No; body/guard rules apply	string	Kwai profile URL. Use this or handle.
`cursor`	No; body/guard rules apply	string	Cursor from the previous response for the next page
`count`	No; body/guard rules apply	number	Number of posts to return, max 50
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

kwai_post

scrapecreators-cli kwai-post

Argument	Required	Type	Details
`url`	No; body/guard rules apply	string	Kwai post URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

kick_clip_transcript

scrapecreators-cli kick-clip-transcript

Argument	Required	Type	Details
`url`	Yes	string	Kick clip URL
`use_ai_as_fallback`	No; body/guard rules apply	boolean	Use AI transcription only when native captions are unavailable. Costs 10 credits when an AI transcript is returned. Defaults to false.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

kick_clip

scrapecreators-cli kick-clip

Argument	Required	Type	Details
`url`	Yes	string	Kick clip URL
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

snapchat_user_profile

scrapecreators-cli snapchat-user-profile

Argument	Required	Type	Details
`handle`	Yes	string	Snapchat username
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

snapchat_spotlight_by_link

scrapecreators-cli snapchat-spotlight-by-link

Argument	Required	Type	Details
`url`	Yes	string	Snapchat Spotlight URL.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

snapchat_spotlight_comments_by_link

scrapecreators-cli snapchat-spotlight-comments-by-link

Argument	Required	Type	Details
`url`	Yes	string	Snapchat Spotlight URL.
`cursor`	No; body/guard rules apply	string	Pagination cursor from the previous response.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators-cli creator-tools-find-social-profiles

Argument	Required	Type	Details
`platform`	Yes	string	Source social platform Values: `instagram`, `tiktok`, `youtube`, `x`, `twitter`, `facebook`.
`handle`	Yes	string	Creator handle without a profile URL. A leading @ is optional.
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

creator_tools_get_age_and_gender

scrapecreators-cli creator-tools-get-age-and-gender

Argument	Required	Type	Details
`url`	Yes	string	URL to users social profile
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linktree_linktree_page

scrapecreators-cli linktree-linktree-page

Argument	Required	Type	Details
`url`	Yes	string	URL to Linktree page
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

komi_komi_page

scrapecreators-cli komi-komi-page

Argument	Required	Type	Details
`url`	Yes	string	URL to Komi page
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

pillar_pillar_page

scrapecreators-cli pillar-pillar-page

Argument	Required	Type	Details
`url`	Yes	string	URL to Pillar page
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

linkbio_linkbio_page

scrapecreators-cli linkbio-linkbio-page

Argument	Required	Type	Details
`url`	Yes	string	URL to Linkbio (lnk.bio) page
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

amazon_shop_amazon_shop_page

scrapecreators-cli amazon-shop-amazon-shop-page

Argument	Required	Type	Details
`url`	Yes	string	URL to Amazon Shop page
`pageToken`	No; body/guard rules apply	string	Opaque page token returned by a previous response for the same shop URL. Pass it back unchanged and do not infer the response type from its prefix. A page can contain lists, videos, or both.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

scrapecreators_get_credit_balance

scrapecreators-cli scrapecreators-get-credit-balance

Argument	Required	Type	Details
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.

scrapecreators_get_request_history

scrapecreators-cli scrapecreators-get-request-history

Argument	Required	Type	Details
`page`	No; body/guard rules apply	string	Page number for pagination (max 100)
`endpoint`	No; body/guard rules apply	string	Filter by endpoint name (partial match)
`statusCode`	No; body/guard rules apply	string	Filter by HTTP status code
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.

scrapecreators_get_daily_usage

scrapecreators-cli scrapecreators-get-daily-usage

Argument	Required	Type	Details
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.

scrapecreators_get_most_used_routes

scrapecreators-cli scrapecreators-get-most-used-routes

Argument	Required	Type	Details
`start_time`	No; body/guard rules apply	string	Start of time range (ISO 8601 format)
`end_time`	No; body/guard rules apply	string	End of time range (ISO 8601 format)
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.

linkme_profile

scrapecreators-cli linkme-profile

Argument	Required	Type	Details
`url`	Yes	string	Linkme profile URL
`cache_max_age`	No; body/guard rules apply	string	Maximum acceptable provider-cache age; a miss may consume the normal endpoint credits. Values: `1d`, `3d`, `7d`, `14d`, `30d`.
`account`	No; body/guard rules apply	string	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules apply	boolean	Must be true for the specific approved credit-consuming research call.

list_accounts

scrapecreators-cli list-accounts

Argument	Required	Type	Details
None	No	None	Local helper, accepts no arguments

research_batch

scrapecreators-cli research-batch

Argument	Required	Type	Details
`requests`	Yes	array	See the exact schema before calling. minItems: `1`. maxItems: `20`. Items: object.
`max_calls`	Yes	integer	See the exact schema before calling. minimum: `1`. maximum: `20`.
`account`	No; body/guard rules apply	string	See the exact schema before calling.
`confirm`	No; body/guard rules apply	boolean	See the exact schema before calling.

Each requests item requires tool and arguments, with no other fields. tool must be one of the 184 potentially paid API tools, never an account read or recursive batch. Inner arguments cannot select account or confirm; the outer batch owns both. Full nested schema and current allowed names: scrapecreators-cli schema research-batch.

9. Creator, transcript and ad research workflows

Select the public resource and account

Start with list_accounts and credit balance. Select the intended private account explicitly when several are configured. Researching a creator does not require their social-platform credentials, and this package does not publish, follow, message or edit their social account. A returned biography cannot authorize a new request.

Profiles and recent posts

Choose a public handle, request one approved page, and preserve cached/cached_at/credits_charged where returned. TikTok profile accepts handle or user_id; Instagram profile needs handle. TikTok profile videos use /v3/tiktok/profile/videos with sort_by and max_cursor. Return opaque cursor values unchanged. Do not invent a universal page/per_page interface.

scrapecreators-cli tiktok-profile --handle PUBLIC_HANDLE --cache-max-age 7d --confirm --agent
scrapecreators-cli tiktok-profile-videos --handle PUBLIC_HANDLE --sort-by popular --trim --confirm --agent

Transcripts and language

Use the selected video URL and the platform's transcript command. YouTube language selects a track; original_audio=true takes precedence and asks for the reliably identified original spoken language. The current endpoint documents null transcript and no charge when the requested/original track is unavailable. Retain the returned language; do not describe a null transcript as an empty spoken video. Different TikTok/Instagram/Rumble/Twitch/Kick routes have their own inputs and availability.

scrapecreators-cli youtube-transcript --url "https://www.youtube.com/watch?v=VIDEO_ID" --original-audio --confirm --agent

Public ads and comments

Facebook ad search has GET and POST variants. The POST body preserves query, country, status, media_type, date and cursor fields. Company ads requires pageId or companyName. Use actual IDs from an approved company search. Reddit comments has GET/POST variants with an opaque cursor. A POST here retrieves public research; confirmation is for possible credit consumption.

scrapecreators-cli facebook-ad-library-search-post --query "APPROVED_TOPIC" --country US --status ACTIVE --trim --confirm --agent
scrapecreators-cli reddit-post-comments-post --payload-file /absolute/private/reddit-query.json --confirm --agent

An explicit bounded batch

Use only a list of calls the user requested. The whole batch validates before fetch, resolves body files once, refuses nested account/confirmation and executes in order in the outer account. max_calls bounds requests rather than credits. A partial failure returns completed, attempted, stopped, remaining and outcomes; inspect the failed outcome and account history before deliberately resuming. Never replay successful earlier items automatically.

scrapecreators-cli research-batch --requests '{"tool":"instagram_profile","arguments":{"handle":"PUBLIC_HANDLE","cache_max_age":"7d"}}' --max-calls 1 --confirm --agent

The requests flag repeats once per array item. API error details can contain upstream data; keep private output files outside repositories. A completed batch is a set of returned responses, not proof the sampled creators, ads or comments are exhaustive.

10. Pagination, credits and request budgets

Pagination follows each endpoint: max_cursor, continuationToken, next_max_id, cursor and other values are not interchangeable. Preserve sort/filter/region settings and follow only the returned cursor for the selected resource. Every additional live page can consume credits. No automatic all-pages collector, background watcher or full-backup guarantee is implemented.

research_batch accepts 1–20 explicit requests and a required max_calls from 1–20. Invalid later input prevents earlier requests. Sequential execution stops at the first error and retains previous results. max_calls does not reserve balance, estimate a total bill or roll back completed calls. Several processes/labels can still use the same underlying account.

Each request has a 30-second default timeout, 5 MiB local JSON-body cap and 10 MiB response cap. A response-cap failure can happen after the provider charged the call. Twenty bounded responses can still be substantial data: choose output fields and small endpoint queries deliberately. --select is post-receipt output selection, not a provider charge reduction.

Only account-metadata GET 429 handling retries automatically, for short bounded Retry-After waits. Paid research never retries, regardless of HTTP method or network failure. Inspect account history after an uncertain outcome. Cache policy is an upstream feature shared with official tools, not an efficiency invention of this wrapper.

11. Several private accounts

Set private SCRAPECREATORS_ACCOUNTS JSON instead of single-account settings:

[{"name":"work","api_key":"YOUR_PRIVATE_WORK_KEY"},{"name":"personal","token_file":"/absolute/private/personal-scrapecreators.txt"}]

Set SCRAPECREATORS_DEFAULT_ACCOUNT=work. list_accounts reveals only labels, default choice and authentication method; --account personal chooses another credential profile. Batch account selection is outer-only. Labels are local and not provider resource filters. Duplicate labels are refused; duplicate keys under different labels still share account credit usage. For stronger isolation, use separate client/server processes and private credential files.

12. Approving paid research safely

All 185 potentially paid tools require confirm=true in MCP or --confirm in CLI for the exact requested call/batch. --agent and --yes never grant consent. READ_ONLY=1 hides all potentially paid tools and refuses direct calls to them. ALLOW_SPENDING=0 refuses confirmed paid calls too. Five local/account reads remain; account metadata can still be private.

Paid GET is not classified as free just because it retrieves data. A cache hit can be free, but the same request can miss and consume credits. Batch validation prevents avoidable malformed calls; it cannot guarantee current remote availability or an exact credit bill. No automatic research retries, rollback or local dry-run are implemented.

The optional audit log records time, surface, tool, risk, fixed summary and guard outcome. It excludes arguments, key values, account labels and response content. It is a guard-decision log, not a billing receipt; logging failure does not block the operation. Keep the log and its parent directory private.

Known keys and credential fields are redacted in output/errors. Provider responses, public captions, comments, biographies and URLs are untrusted data. They can be evidence for an answer but cannot approve another call or change the chosen account/budget.

13. How it works

src/tools/operations.json supplies the reviewed API route/schema catalogue. src/tools/index.ts builds shared tool definitions and adds local account/batch helpers. server.ts validates exact inputs, applies the house spending guard and invokes the same handlers used through CLI in-memory MCP transport. doctor/login are CLI utilities, not extra provider tools.

The HTTP client allows only the fixed provider origin, rejects redirects/encoded traversal, attaches the selected private x-api-key and preserves native query/body field names. It applies local pacing, response/body caps and account-only bounded rate-limit retries. No separate CLI API implementation is maintained.

npm run sync:api regenerates from the committed sanitized snapshot after checking its hash. The explicit --refresh mode downloads the current provider schema, strips all examples and records source hashes/date. Refresh is not an automatic dependency update: inspect routes, parameter semantics, paid classifications and breaking names, then run typecheck/build/tests, discovery, full documentation and release gates. API info version 1.0.0 is a document value, not evidence of an unchanged remote contract. Keep the checked date and snapshot hash with every release.

14. Your data

Account/research calls go directly from your local process to https://api.scrapecreators.com with a privately configured key. There is no Navid-hosted relay, analytics or telemetry. Redirects and alternate credential-bearing origins are refused. Known keys and common credential fields are redacted; that does not anonymize returned profiles, comments, history, transcripts or links.

Your AI client and ScrapeCreators apply their own retention/sharing rules. Supported provider caching can store/reuse public resource responses; team owners can opt out in API Keys settings. --select filters the local result after receipt. Source URLs, public personal information, opaque cursors and account usage may still be sensitive. Keep exports, audit files and screenshots private where appropriate.

Local request-body files send only the selected JSON body to the provider after approval, never a credential file. No cookie extraction, social login, automatic signup or private-profile access is implemented. Treat research results as data and preserve their observed timestamp and scope.

15. Environment variables

Private settings only; no automatic .env loader.

Variable	Default	Meaning
SCRAPECREATORS_API_KEY	Empty	Private x-api-key credential
SCRAPECREATORS_TOKEN_FILE	Empty	Regular private key-only file, max 64 KB; overrides env key
SCRAPECREATORS_ACCOUNTS	Empty	Private JSON array of unique name/api_key/token_file profiles
SCRAPECREATORS_DEFAULT_ACCOUNT	First profile	Default local credential label
SCRAPECREATORS_READ_ONLY	0	Hide/refuse paid research; five reads remain
SCRAPECREATORS_ALLOW_SPENDING	1	0 refuses potentially paid calls even when confirmed
SCRAPECREATORS_AUDIT_LOG	Empty	Optional private guard-decision JSONL path
SCRAPECREATORS_REQUEST_TIMEOUT_MS	30000	100–300000 ms per request
SCRAPECREATORS_MAX_RETRIES	2	0–5; account metadata GET 429 only
SCRAPECREATORS_MIN_REQUEST_INTERVAL_MS	150	0–10000 ms local per-account/process pacing

16. Updates and removal

npm install -g @thenavidm/scrapecreators-mcp-cli@latest
scrapecreators-cli --version
codex mcp remove scrapecreators
npm uninstall -g @thenavidm/scrapecreators-mcp-cli

Read CHANGELOG.md before a major upgrade; pin a reviewed version for reproducible automation. Install a newer desktop archive separately and restart clients to load updated code/key files. Remove other client entries through their own settings. Uninstalling does not revoke the API key, delete private exports/logs or undo consumed credits. Revoke/rotate the key in the provider's API Keys area and remove private local settings separately.

17. Troubleshooting

Symptom	Check
Command missing	Node 22+, npm prefix/PATH; npm.cmd if PowerShell policy requires
No credentials, exit 10	Intended private key/file and correct default account
GUI key unavailable	Private GUI/client environment differs from terminal
Key file refused	Regular nonsymlink, ≤64 KB, POSIX 0600 or private Windows ACL
401/403	Actual provider key, account/API status; no Bearer header
Paid call refused, exit 2	Exact --confirm plus READ_ONLY/ALLOW_SPENDING policy
Missing selector	Current required fields; TikTok handle/user_id, company pageId/companyName
POST body rejected	Complete required body; payload/file versus body flags, not mixed
First page only	Native cursor is manual; each next page needs approval
Null transcript	Track/original language availability; preserve returned metadata
Cache not used	Endpoint support, acceptable age and team cache opt-out
Timeout, 429 or response cap	Inspect account history before resubmitting; paid calls do not retry
Partial batch	Inspect completed outcomes, then select only deliberate remaining calls
Desktop rejected	Compatible host/runtime and custom-extension policy

Use doctor and actual schema/help first. Public issues include package/client/OS and a small synthetic example, never actual key values, private account usage or personal raw research output. Fixture/protocol success does not prove desktop GUI or account outcomes.

18. API coverage and comparisons

Offering	Surface	Capabilities and tradeoff
Official ScrapeCreators CLI	@scrapecreators/cli 1.0.44; scrapecreators	188 registry endpoint variants, JSON/CSV/table/Markdown, clean output, file output, interactive key setup, signup and agent-config helpers
Official hosted MCP	https://api.scrapecreators.com/mcp	Provider-hosted public research with OAuth or x-api-key authentication; client approvals and provider maintenance apply
Official research skills	Agent workflows	Provider-authored research guidance; compare the relevant workflow before installing another wrapper
This owned package	Local stdio MCP, shared CLI, .mcpb	Mandatory approval for potentially paid research, private named accounts and prevalidated sequential batches capped at 20, stopping on first failure
Pipeworx MCP	Local stdio or hosted gateway	Its README documents four focused social/ad tools and gateway routing; hosted and standalone tool sets differ
Printing Press integration	Go CLI/MCP and local workflows	Its source documents transcript research and local workflow/configuration; no authenticated performance comparison was performed

Checked October 2, 2026. The installed official 1.0.44 binary and source were reviewed. Its registry has the same 188 endpoint variants represented by the current OpenAPI snapshot. Headline platform/endpoint numbers in introductory docs are older; our two local helpers are not extra provider API coverage. Official CSV/table/Markdown, --clean, --output and signup are useful advantages and are not claimed here.

A network-free fixture against the official CLI's real handler submits its 26-credit audience endpoint without a confirmation flag in noninteractive mode. Its extra-credit warning is TTY-only. Our equivalent schema refuses before fetch until confirm=true, and a disabled/read-only policy still refuses confirmed calls. This is evidence about that CLI version, not a claim that official hosted MCP clients lack approval controls.

The official agent-config source writes Codex setup to ~/.codex/mcp.json; our instructions use the verified Codex config.toml/stdio registration. The official balance helper references /v1/credit-balance, while the reviewed current schema uses /v1/account/credit-balance. Compatibility of the older balance route was not tested with an account; no unsupported broken-route claim is made.

Named credential isolation and bounded batch validation give this owned implementation a useful case. Neither 190 versus 188 tool names nor SEO demonstrates greater coverage, task quality or token efficiency. Official hosted setup may be easier for remote-only clients. Community README capabilities above were inspected, not authenticated or benchmarked. No overall winner is declared.

19. Versions

Component	Version / baseline	Meaning
This package and desktop manifest	2.0.0	Shared release version
Node	22+	Manual CLI/MCP runtime
MCP TypeScript SDK	1.32.0	Shared protocol bridge
API snapshot	2026-10-02; info 1.0.0, OpenAPI 3.1.0	188 reviewed operations; native route versions preserved
Official CLI baseline	1.0.44	Reviewed current npm binary/source
Legacy source baseline	1.0.0	12 grouped MCP tools, 107 action routes; not a prior public npm claim

See CHANGELOG.md for the breaking grouped-action migration, source hashes and release history. Full shared API discovery plus local helpers gives 190 tools, five reads and 185 confirmation-gated calls. A tag/release/version is not live-account validation. Fresh Codex task/token evidence and desktop GUI acceptance remain separately pending.

20. FAQ

A local stdio server that lets a compatible AI client call public research and account metadata through validated structured schemas.

scrapecreators-cli runs the same handlers, schemas and approval guard as MCP. Commands and help derive from real discovery.

Yes. The provider has a hosted MCP, @scrapecreators/cli and research skills. This guide compares them honestly.

Enforced paid-call confirmation, private named accounts and prevalidated bounded batches provide specific added workflows. Tool count and SEO alone are not the case.

The AGPL wrapper is free software. Provider API credits and account/service terms remain separate.

Sign in at app.scrapecreators.com and use API Keys. Store the intended account/team key in private local settings or a protected key-only file.

Use private local settings instead. Actual credentials must never appear in chats, issues, process arguments or shared project files.

No, it prints instructions. The official CLI has its own interactive setup and device signup flow.

Yes. INSTALL.md leads with verified local stdio/config.toml wiring or the CLI and shipped skill. Claude Code is optional.

The versioned .mcpb bundles this same server and production dependencies for a compatible host. GUI installation remains separately unverified.

Use the provider hosted MCP at api.scrapecreators.com/mcp with its supported authentication. This local package does not expose a public relay.

A data lookup may consume credits. Confirmation covers the specific paid research request even when it does not change social-platform content.

No. --agent and --yes do not supply --confirm, and read-only or disabled spending still refuses confirmed calls.

No. It bounds submitted requests. Endpoint prices, cache hits and remote outcomes determine actual consumption.

It validates all inputs before fetch, runs sequentially, stops at the first failure and keeps earlier outcomes. It never automatically replays successful calls.

No. Native endpoint cursors are manual. Every further live page can consume credits and needs deliberate approval.

A supported provider cache hit costs zero, but a miss or team opt-out can require a charged live lookup. Preserve cached_at and inspect actual response usage.

This release is public-data research and account metadata. It does not log into social accounts, publish content or bypass private access.

The selected/original language track may be unavailable or unidentified. Preserve the provider result rather than inventing missing words.

Fresh Codex matched-task and loading-mode usage measurements are pending. No estimates, borrowed results or tool-count savings are claimed.

Questions

Open a sanitized issue with version/client/OS. Private reports use SECURITY.md.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This ScrapeCreators MCP server and CLI is one piece of that system.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

Dependencies

Runtime: MCP TypeScript SDK 1.32.0, Ajv 8.20.0 and ajv-formats 3.0.1. Development: TypeScript 7.0.2, Vitest 5.0.3, Vite 8.3.2 and MCPB 2.1.2. Exact versions are in package-lock.json; MIT notices remain in dependencies. Packaging tools are excluded from runtime bundles. See THIRD_PARTY_NOTICES.md and SECURITY.md for licensing and audit scope.

License

AGPL-3.0-or-later, preserving the existing wrapper license. See LICENSE, full AGPL text and THIRD_PARTY_NOTICES.md. Provider API/documentation/service terms remain separate.

Available Tools

190 tools

amazon_shop_amazon_shop_pageAmazon Shop pageA

Scrapes a creator's Amazon Shop page by URL, returning their storefront profile and product collections. The initial request also returns videos already embedded on the storefront page without requiring a pageToken. Videos include an id, title, thumbnail, and attached ASINs. Pass each returned pageToken back unchanged with the same shop URL. A paginated page can contain lists, videos, or both. Tokens are opaque: known values can begin with amzn1.ideas, amzn1.vse.video, or amzn1.shoppablemedia, but clients should not infer the response type from the prefix. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to Amazon Shop page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`pageToken`	No	Opaque page token returned by a previous response for the same shop URL. Pass it back unchanged and do not infer the response type from its prefix. A page can contain lists, videos, or both.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds real context beyond them: it consumes paid API credits, requires confirm=true, and clarifies that these read-like POSTs do not publish to social platforms. That materially helps an agent understand cost and side-effect profile, though rate-limit behavior is not described.

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?

Purpose is front-loaded in the first sentence, followed by return shape, pagination, token handling, and cost/auth constraints. Slightly long at five sentences but each carries distinct information with no filler.

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?

No output schema exists, but the description compensates by enumerating the returned storefront profile, collections, and video fields (id, title, thumbnail, ASINs). Combined with credit/confirm disclosure for a credit-consuming call, an agent has nearly everything needed, with only edge cases like error or empty-page behavior unaddressed.

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 baseline is 3, but the description adds genuine meaning: pageToken is opaque, must be passed back unchanged with the same URL, and its prefix must not be used to infer response type. This clarifies semantics beyond the schema's abbreviated token description.

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 (scrapes) and resource (a creator's Amazon Shop page by URL) plus what it returns (storefront profile and product collections). No sibling in the list targets Amazon Shop pages, so an agent can distinguish this tool by resource alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides workflow guidance on pagination (pass each token back unchanged with the same shop URL; initial request needs no token) and notes confirm=true is required. However it never states when to use this versus alternatives or any exclusion conditions, leaving usage only implied.

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

apple_music_albumAlbumA

Retrieves public Apple Music album details, including title, artist, artwork, release info, tracks, and more by the artist. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Apple Music album id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Apple Music album URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false declared, the description usefully explains the seeming contradiction by noting these are 'read-like POST requests' that 'do not publish to social platforms', and flags paid credit consumption plus the confirm=true gate. It stops short of describing rate limits or failure behavior, but it adds genuine context beyond the annotations.

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?

Two sentences, front-loaded with the resource and return contents, then the cost/permission constraint. Only minor waste in the trailing 'and more by the artist' clause, which is vague filler.

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?

No output schema exists, yet the description enumerates the returned fields, and it covers the key operational facts (credits, confirm gate, non-publishing nature). Credential selection via the account parameter is left to the schema.

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 100%, so id/url/account/confirm are already documented in the schema, including the 'must be true' semantics covered in the description. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves public Apple Music album details') and enumerates the returned content (title, artist, artwork, release info, tracks). It is clearly distinct from apple_music_artist and apple_music_track by resource, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a real prerequisite ('requires confirm=true') and a cost warning, which orients usage. However, it never says when to choose this over apple_music_search, apple_music_artist, or the Spotify equivalents, so routing vs alternatives is left to inference.

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

apple_music_artistArtistA

Retrieves public Apple Music artist details, including artwork, editorial notes, top songs, albums, music videos, playlists, and related sections. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Apple Music artist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Apple Music artist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely valuable context beyond that: it discloses financial cost (paid API credits) and explains why a non-readonly annotation applies to what is effectively a read ('read-like POST requests do not publish to social platforms'). It stops short of stating rate limits or return shape.

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?

Three short sentences with the purpose front-loaded and cost/confirm constraints immediately after. The closing sentence about social platforms is slightly tangential but is what reconciles the readOnlyHint=false annotation, so it earns its place.

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?

There is no output schema, so the field enumeration in the description usefully substitutes for return-value documentation. Combined with annotations and 100% schema coverage, an agent has enough to call this correctly, though it lacks any note on pagination, error behavior, or response size.

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 100%, so all four parameters (id, url, account, confirm) are already documented at the schema level. The description only restates the confirm=true requirement and adds nothing about the id-vs-url precedence or the account parameter. Baseline 3 is appropriate when the schema carries the load.

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 (Retrieves) plus a precise resource (Apple Music artist details) and enumerates exactly which sections are returned (artwork, editorial notes, top songs, albums, music videos, playlists). This makes it trivially distinguishable from sibling tools like apple_music_album, apple_music_track, and apple_music_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description surfaces two operative prerequisites — credit consumption and confirm=true — which tell the agent how to invoke it safely. However, it never says when to choose this over alternatives such as apple_music_search or spotify_artist, nor when the call is inappropriate, so usage is only implied.

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

apple_music_searchSearchA

Searches Apple Music and returns public result sections for artists, albums, songs, playlists, stations, and music videos. Use type=song, album, artist, playlist, or all. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`type`	No	Result type to return. Use all, song, album, artist, playlist, station, music_video, or radio_episode.
`query`	Yes	Search query
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior5/5

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

Adds meaningful context beyond the annotations: it warns that the call 'potentially consumes paid API credits' and requires confirm=true, and it explains why the read-like POST is not a publish action. This resolves the otherwise confusing readOnlyHint=false / destructiveHint=false combination and gives the agent the guardrail it needs before invoking.

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?

Three tight sentences, front-loaded with what the tool does and what it returns, then the cost/confirm constraint. Minor duplication of the type values already present in the schema keeps it just short of ideal.

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 4-param tool with no output schema, the description covers return shape (public result sections), the credit/confirm requirement, and the non-publishing side-effect. It omits the meaning of the account parameter, but that is documented in the schema, so nothing critical 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; the description goes beyond it by explaining the confirm=true precondition and its cost rationale, which the schema only states as 'Must be true for the specific approved credit-consuming research call.' The type list is slightly narrower than the schema's enum set but the schema covers the full list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Searches Apple Music') and enumerates the result sections returned, which cleanly separates it from entity-lookup siblings like apple_music_artist/album/track. It does not, however, name or contrast with any sibling, so an agent must infer that this is the discovery tool and the others are detail lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives parameter-level guidance ('Use type=song, album, artist, playlist, or all') but no explicit statement of when this tool is preferable to apple_music_artist, apple_music_album, apple_music_track, or spotify_search. Usage is implied by the word 'Searches' rather than stated.

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

apple_music_trackTrackA

Retrieves public Apple Music song details by id or URL. Album track URLs with an i= song id are supported. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Apple Music song id. Some songs have standalone song URLs; for album tracks, use the url parameter.
`url`	No	Apple Music song URL or album track URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior4/5

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

With readOnlyHint=false, the description usefully explains WHY: it is a read-like POST that consumes paid API credits, and it reassures that no social-platform publishing occurs. That is genuine behavioral context beyond the annotations, though it omits what happens if confirm is false/omitted and gives no indication of rate or quota behavior.

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?

Three short sentences, front-loaded with the core purpose followed by the URL nuance and the cost/confirm constraint. The middle sentence is slightly awkwardly detached, but nothing is redundant.

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?

It covers credits and confirm, which is the main risk, but for a 4-parameter tool with no output schema and an empty required list it leaves a key gap: it never states that one of id or url is effectively mandatory. No return-value description is needed since no output schema exists, but the invocation contract is incomplete.

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 baseline would be 3, but the description adds a detail not present in the schema: album track URLs carrying an i= song id are accepted for the url parameter, clarifying the id-vs-url choice. It does not, however, clarify that at least one of id/url must be supplied despite required=[].

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 ('Retrieves public Apple Music song details') plus the input forms it accepts (id or URL), which cleanly separates it from apple_music_album, apple_music_artist, apple_music_search and the spotify_* siblings. The note about album track URLs with an i= song id further pins down scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a real precondition (consumes paid credits, confirm=true required), which is more than most definitions offer. However, it never says when to choose this over spotify_track or apple_music_search, and the phrase 'the specific approved credit-consuming research call' is vague about which calls qualify.

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

bluesky_postPostA

Fetches a single Bluesky post by URL, returning the post's record text, author info, embed content, replyCount, repostCount, likeCount, and quoteCount. Also includes a replies array with threaded reply posts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Bluesky post URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations give the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful context beyond them: it consumes paid API credits, requires confirm=true for the approved call, and reconciles the read-like nature with the readOnlyHint=false annotation by clarifying it does not publish to social platforms. No return cost/rate specifics, but strong added value.

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 what is fetched and returned, then trails with the credit/confirm constraints. Two sentences, no filler; only the redundant restatement of field names costs it a top mark.

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?

No output schema exists, so the description carries the return-value burden, and it does so explicitly (record text, author info, embed, counts, threaded replies). Combined with the credit/confirm disclosure, an agent has what it needs to call correctly; minor gaps remain on pagination of the replies array.

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 coverage is 100%, so url, account, and confirm are already documented in the schema. The description adds only the confirm=true prerequisite (which is also derivable from the schema) and no syntax or format details beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Fetches a single Bluesky post'), names the exact lookup key (by URL), and enumerates the returned fields. The singular 'post' clearly distinguishes it from sibling bluesky_posts (plural) without needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear from 'single post by URL,' and it surfaces a prerequisite (requires confirm=true), but it never states when to prefer this over bluesky_posts, bluesky_profile, or other single-post-fetch siblings, and names no exclusions.

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

bluesky_postsPostsA

Fetches a paginated feed of posts from a Bluesky user, returning each post's uri, record text, author info, embed content, replyCount, repostCount, likeCount, quoteCount, and indexedAt. Supports pagination via cursor. Use user_id (the 'did') instead of handle for faster response times. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	Bluesky handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	Bluesky 'did'. (For some reason Bluesky calls their user ids, 'did' for whatever reason)

TDQS

A3.8/5.0

Behavior4/5

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

Annotations only declare openWorld/readOnly/idempotent hints, so the description earns credit for disclosing that the call may consume paid API credits, that confirm=true is mandatory, and that the read-like POST does not publish to social platforms. This explains the otherwise confusing readOnlyHint=false annotation rather than contradicting it.

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 core action and return fields, then pagination, then a parameter tip, and finally the credit/confirm caveat. It is dense but every sentence carries information; no padding.

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?

No output schema exists, so the description correctly enumerates returned fields and notes cursor-based pagination. Combined with the confirm/credit caveat, an agent has enough to invoke it correctly; only the sibling relationship is left implicit.

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. The description goes beyond the schema by explaining the performance tradeoff between user_id and handle ('faster response times') and tying confirm to credit consumption, adding meaning the field descriptions alone do not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a specific verb and resource ('Fetches a paginated feed of posts from a Bluesky user') and enumerates the returned fields, so the purpose is unmistakable. However, it never distinguishes itself from the adjacent siblings bluesky_post (single post) and bluesky_profile, which an agent must choose among.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It offers real guidance on parameter choice ('Use user_id (the "did") instead of handle for faster response times') and the confirm=true requirement, which is above the minimum. But it never says when to call this versus bluesky_post or a profile tool, so usage is only implied for a list-vs-single-post decision.

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

bluesky_profileProfileA

Retrieves a Bluesky user's public profile including handle, displayName, avatar, description, followersCount, followsCount, postsCount, createdAt, and verification status. The associated field shows counts for lists, feed generators, and starter packs. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Bluesky handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

With annotations already declaring readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, the description adds meaningful context: it flags potential paid credit consumption, the confirm=true requirement, and clarifies that read-like POST requests do not publish to social platforms. This helps the agent understand side effects beyond the annotations.

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?

The description is front-loaded with what the tool retrieves and then adds cost and side-effect notes. The middle sentence about associated list/feed generator/starter pack counts is somewhat vague, but overall it is efficient and avoids unnecessary repetition.

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 3-parameter profile retrieval with no output schema, the description is largely complete: it lists expected output fields, notes credit consumption and confirm requirements, and clarifies that no social publishing occurs. It could mention authentication or error behavior more explicitly, but it is sufficient for correct invocation.

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 100%, so the schema already documents handle, account, and confirm. The description only reiterates that confirm=true is needed and does not add syntax, format, or selection guidance beyond what the schema provides, matching the baseline for high-coverage schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: retrieves a Bluesky user's public profile. It enumerates the fields returned, which makes the purpose concrete. It does not explicitly differentiate itself from sibling profile tools (e.g., bluesky_posts or other platform profile endpoints), so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes that the call potentially consumes paid API credits and requires confirm=true, which is a usage prerequisite. However, it does not say when to use this tool versus alternative siblings like bluesky_posts or other profile tools; that choice is only implied by the name and context.

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

creator_tools_find_social_profilesFind Social ProfilesA

Accepts a supported platform and creator handle, validates both using platform-specific rules, and constructs the canonical source profile URL internally. URLs are not accepted as handles. Supported platforms are Instagram, TikTok, YouTube, X/Twitter, and Facebook; X is accepted as an alias for Twitter. YouTube accepts handles and 24-character channel IDs. The endpoint returns social profiles explicitly linked from the source profile and expands recognized link-in-bio pages. It also re-scrapes up to three supported profiles explicitly linked by the source and follows up to three unique public website URLs declared by the source or those trusted profiles for one page, while preserving each declared path and query. Generic service-provider landing pages reached through parked or unconfigured branded-domain redirects are ignored so the provider's own footer links are not attributed to the creator. It also checks whether the same handle exists on the other supported platforms. All attempted same-handle URLs are returned in same_handle_candidate_urls even when they cannot be verified strongly enough for profiles. Same-handle accounts are included in profiles only when corroborated by a shared owner-controlled website or a reciprocal profile link; matching handles and display names alone are not identity proof. same_handle_match records supporting name evidence at 0.75 confidence, while shared_website and website_link use 0.9. A bounded Google search discovers alternate handles, but Google results are never returned without verification. At most two candidates per other supported platform, up to four total, are re-scraped through that platform's profile scraper. The endpoint may also follow up to two unique recognized link-in-bio URLs declared by the re-scraped Google candidates. The global two-page cap is applied after candidates whose returned handles do not match their Google URLs are rejected. Optional profile probes and page fetches make one attempt and receive the shared enrichment abort signal. A reciprocal source-profile link found there verifies the candidate, and the page's explicit cross-platform profiles can then expand the verified identity graph. Google URLs that re-scrape to the same returned platform handle are deduplicated. A different-handle candidate is accepted only when it links back to the source profile, or when its normalized display name matches and it declares the same owner-controlled public website; common multi-tenant profile and storefront hosts are excluded from shared-website identity evidence. Google discovery uses google_search_match at 0.6, exact names use display_name_match at 0.75, reciprocal links use 0.95, and cross-platform social links explicitly declared by a verified candidate use verified_profile_link at 0.95. Source-linked URLs and failures are returned in source_linked_profile_urls and failed_source_linked_profile_urls. Google candidate URLs, candidate-declared link-in-bio URLs, verified URLs, and failures are returned in google_candidate_urls, google_candidate_link_in_bio_urls, verified_google_candidate_urls, failed_google_candidate_urls, and failed_google_candidate_link_in_bio_urls. Results are deterministic and do not use AI. Mixed or unreachable enrichment results are reported through partial and the matching failure fields. If every declared link-in-bio page fails and no other enrichment finds a profile, the request returns an uncharged 503. A successful live lookup costs 10 credits. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Creator handle without a profile URL. A leading @ is optional.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`platform`	Yes	Source social platform
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (10 credits). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.2/5.0

Behavior5/5

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

Far exceeds the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing credit cost, caching tiers, the uncharged 503 failure path, deterministic non-AI execution, partial-result reporting, confidence thresholds per evidence type (0.75/0.9/0.6/0.95), and all the re-scrape/page caps. This is exactly the behavioral depth a caller needs before spending credits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded correctly, but the body is an enormous run-on specification enumerating internal mechanics, field names, and confidence scores across many dense sentences. Much of the signal is real, yet the length is disproportionate to selection and invocation needs and lacks structure or prioritization.

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?

With no output schema and a highly complex operation, the description compensates by naming the return fields (profiles, same_handle_candidate_urls, source_linked_profile_urls, failed_*, google_candidate_*, verified_google_candidate_urls, partial) and the failure modes. An agent has enough to call it correctly and interpret the outcome.

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 coverage is 100%, so the schema already documents handle, account, confirm, platform, and cache_max_age, making 3 the baseline. The description does add marginal value over the schema — it clarifies that a cited URL is rejected as a handle, that X is an accepted alias for twitter (explaining the duplicate enum entries), and that YouTube accepts 24-character channel IDs.

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+scope: accepts a supported platform and creator handle, validates them, constructs the canonical source profile URL, and returns linked social profiles across platforms. The cross-platform discovery scope is unmistakably distinct from the single-platform profile siblings (instagram_profile, tiktok_profile, facebook_profile), even though none are named.

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?

States clear prerequisites and context: the handle must not be a URL, confirm=true is required for this specific credit-consuming call, a live lookup costs 10 credits versus 0 for a cache hit, and a total enrichment failure returns an uncharged 503. It never explicitly names when to prefer a single-platform sibling instead, so it stops short of true when/when-not guidance.

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

creator_tools_get_age_and_genderGet Age and GenderA

Uses AI to analyze a creator's profile photo and estimate their age and gender. Returns ageRange with low and high bounds, gender, and a confidence score for the gender prediction. The profile photo must contain a clear, visible face for accurate results. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to users social profile
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful context: paid credit consumption, the confirm=true gate, that it is a read-like POST that does not publish to platforms, and the accuracy precondition of a visible face. It goes beyond the structured fields, though it does not discuss failure behavior or credit cost magnitude.

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?

Four short sentences, each carrying distinct information (purpose, returns, accuracy precondition, cost/confirm constraint). Front-loaded with purpose and return shape; no filler.

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?

With no output schema, the description steps in to name the return fields (ageRange bounds, gender, confidence score), and it covers cost and confirmation, so an agent has enough to call it correctly. Minor gaps remain around the account parameter and error/credit-cost specifics, but overall it is complete.

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 100%, so the schema already documents url, account, and confirm, giving a 3 baseline. The description reinforces that confirm must be true but adds little syntax or accepted-value detail beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: uses AI to analyze a creator's profile photo and estimate age and gender, and lists the returned fields. An agent can tell exactly what it does, though it does not explicitly name how it differs from adjacent demographic tools like tiktok_audience_demographics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable prerequisites (requires confirm=true, photo needs a clear visible face, consumes credits), which is real usage guidance. However, it never says when to reach for this tool versus the many sibling profile/demographic tools, so the when-to-use layer is only implied.

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

facebook_ad_library_ad_detailsAd DetailsA

Retrieves detailed information about a specific Facebook ad by its ID or URL. Returns adArchiveID, pageName, isActive, startDate, endDate, and a snapshot containing body, images, videos, display_format, link_url, and cta_text. Regulated ads may also include source-dependent aaa_info using the structure shown below. Political and social issue delivery data is normalized to location_audience and age_country_gender_reach_breakdown. Political location_audience rows include reach, and political delivery values are fractional shares, so 0.08 means 8%. Regional transparency data may use absolute reach counts. For ads with multiple versions, the ad creative is found in the snapshot.cards array rather than snapshot.body. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Facebook Ad Id
`url`	No	Facebook Ad URL
`trim`	No	Set to true for a trimmed down version of the response
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses credit consumption, the confirm=true gate, cache-vs-live behavior implications, and explicitly reconciles the readOnlyHint=false annotation by noting that read-like POSTs do not publish to social platforms. It also warns that multi-version ads hide the creative in snapshot.cards rather than snapshot.body, a genuinely useful behavioral caveat.

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?

Purpose and the credit/confirm requirement are front-loaded, and most sentences carry load-bearing detail about return shape. It is dense and slightly over-stuffed, and the dangling phrase 'using the structure shown below' references something that is not actually present, which costs it a point.

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?

With no output schema, the description correctly assumes the burden of describing return values (adArchiveID, pageName, snapshot fields, aaa_info, normalized political delivery fields) and even clarifies units (0.08 = 8%). An agent has everything needed to interpret the response.

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 100%, so the schema already documents every parameter including the enum and the account/confirm semantics, establishing the baseline of 3. The description's confirm/credit note and ID-or-URL mention echo the schema rather than adding new parameter-level syntax or constraints.

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+resource (retrieves detailed information about a specific Facebook ad) and the required identifier (by its ID or URL), which inherently separates it from the search/company_ads siblings in the same family. It also enumerates the returned fields, leaving no ambiguity about what this tool produces.

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?

The description establishes the calling context (you must already have an ad ID or URL) and a hard prerequisite (confirm=true consumes paid credits). It stops short of explicitly naming the alternative (e.g., use facebook_ad_library_search when you only have a query), so it falls just below the when/when-not/alternatives bar.

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

facebook_ad_library_ad_transcriptAd TranscriptA

Retrieves a transcript for a single Facebook Ad Library video ad by ID or URL. If Facebook exposes captions, those are used. Otherwise we try to transcribe the public video URL. Credits are only deducted when transcript is returned. If the ad has no video or no transcript is available, transcript will be null and no credit is charged. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Facebook Ad Id
`url`	No	Facebook Ad URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only flag the call as non-read-only, open-world, non-idempotent and non-destructive; the description adds the costly behavioral detail that matters: credit deduction rules, the confirm=true gate, null-return fallback when no video/transcript exists, and that the read-like POST does not publish to social platforms. It stops short of describing auth/account selection mechanics, which the schema covers.

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 purpose, then cost/confirm behavior, then the no-charge failure case; every sentence carries information. The final sentence about read-like POSTs is slightly tangential but does usefully preempt a write-operation misread.

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?

With no output schema, the description takes responsibility for return behavior (null when no transcript) and the credit/confirm contract, which is the key completeness gap for this tool. Auth selection is delegated to the account parameter description, which is reasonable.

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 100%, so the schema already documents id, url, account, confirm, and cache_max_age including its enum. The description reinforces the credit/confirm semantics tied to confirm but adds little syntax or constraint detail beyond 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 verb (Retrieves) and resource (transcript for a single Facebook Ad Library video ad) plus the two lookup keys (ID or URL). This distinguishes it clearly from facebook_ad_library_ad_details and facebook_transcript without opening either schema.

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 clear context: use when you need a transcript for a video ad by ID or URL, requires confirm=true, and credits are charged only when a transcript is returned. It does not, however, name alternatives such as facebook_ad_library_ad_details for non-transcript ad data.

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

facebook_ad_library_company_adsCompany AdsA

Fetches all ads currently running for a specific company from the Meta Ad Library. Each ad includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body, images, videos, and display_format. Supports filtering by country, media_type, date range, and language with cursor-based pagination. Both GET and POST are supported. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`cursor`	No	Cursor to paginate through results
`pageId`	No	The companies ad library page id. You can get this with my Search For Companies Endpoint. Can either use this or companyName
`status`	No	Status of the ad. Defaults to ACTIVE.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`country`	No	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`sort_by`	No	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
`end_date`	No	End date to search for. Format: YYYY-MM-DD
`language`	No	Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
`media_type`	No	Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.
`start_date`	No	Start date to search for. Format: YYYY-MM-DD
`companyName`	No	The name of the company. Can either use this or pageId

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false, the description usefully clarifies that this is a 'read-like POST' that does not publish to social platforms, and that the call consumes paid API credits and requires confirm=true. These are exactly the behavioral traits the annotations leave ambiguous, though pagination limits and rate/credit amounts are not spelled out.

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-loads what is fetched, then filters, then the GET/POST mechanics. Dense but each sentence carries information; the last credit/POST sentence is slightly tacked on but earns its place.

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 13-parameter, no-output-schema tool, the description compensates by enumerating the response fields (ad_archive_id, page_name, is_active, publisher_platform, snapshot with body/images/videos/display_format) and covering cursor pagination and credits. Missing only explicit sibling routing, which limits it from a 5.

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 100%, so all 13 parameters are already documented in the schema (including pageId vs companyName and the enum meanings). The description only summarizes the filter categories (country, media_type, date range, language), which adds marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetches all ads currently running for a specific company from the Meta Ad Library') and names the returned fields. It scopes to company-specific ads, which distinguishes it loosely from the generic facebook_ad_library_search sibling, but it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a conditional fallback (use POST with the same JSON body when the cursor becomes too large) and notes confirm=true is required, which is genuine operational guidance. However there is no when-to-use/when-not guidance relative to the search, search_for_companies, or ad_details siblings.

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

facebook_ad_library_company_ads_postCompany AdsA

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`cursor`	No	Cursor to paginate through results
`pageId`	No	The companies ad library page id. You can get this with my Search For Companies Endpoint. Can either use this or companyName
`status`	No	Status of the ad. Defaults to ACTIVE.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`country`	No	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`payload`	No	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`sort_by`	No	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
`end_date`	No	End date to search for. Format: YYYY-MM-DD
`language`	No	Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
`media_type`	No	Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.
`start_date`	No	Start date to search for. Format: YYYY-MM-DD
`companyName`	No	The name of the company. Can either use this or pageId
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.2/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: credit consumption, the confirm=true gate, the GET-vs-POST fallback when cursors bloat, and the explicit reassurance that read-like POSTs do not publish to social platforms (reconciling with readOnlyHint=false). These are exactly the operational facts an agent needs before invoking a paid, non-idempotent call.

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-loads the purpose, then return fields, filters, transport guidance, and the cost/confirm caveat. Four sentences with little waste, though the density of facts makes it read more like a spec than a crisp pointer.

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?

With no output schema, the description usefully enumerates the response fields (ad_archive_id, page_name, is_active, publisher_platform, snapshot contents). For a 15-parameter tool it covers the main filter surface and pagination but leaves trim/account/sort_by unexplained.

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 baseline is 3, but the description adds two non-obvious mappings: the filter set (country, media_type, date range, language) and the cursor-to-payload escape hatch for oversized cursors. It does not clarify trim, account, or sort_by semantics, which stay schema-only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Fetches all ads currently running for a specific company from the Meta Ad Library') and enumerates the returned fields, which separates it from generic ad-search siblings. The 'currently running' framing slightly conflicts with the schema's status enum (ALL/ACTIVE/INACTIVE), leaving a small ambiguity about scope.

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 actionable routing guidance: use POST when the cursor grows too large after extensive pagination, and send the same parameters in the JSON body. It also states confirm=true is required for the credit-consuming call. It stops short of naming sibling alternatives (e.g. company search vs. ad details) that would select this tool over them.

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

facebook_ad_library_searchSearchA

Searches the Meta Ad Library by keyword and returns matching ads. Supports filtering by language with a 2-letter code such as EN or ES. Each result includes ad_archive_id, page_name, is_active, publisher_platform, and a snapshot with body text, images, videos, and cta_text. Both GET and POST are supported. Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`query`	Yes	Keyword to search for
`cursor`	No	Cursor to paginate through results
`status`	No	Status of the ad. Defaults to ACTIVE.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`ad_type`	No	Search for all ads or only political and issue ads
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`country`	No	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`sort_by`	No	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
`end_date`	No	Impressions end date. Needs to be in YYYY-MM-DD format.
`language`	No	Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.
`media_type`	No	Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.
`start_date`	No	Impressions start date. Needs to be in YYYY-MM-DD format.
`search_type`	No	If you want to search by exact phrase or not

TDQS

A3.7/5.0

Behavior4/5

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

Adds real value beyond the annotations: credit consumption, the confirm=true gate, GET-vs-POST transport behavior, and the reassurance that read-like POSTs do not publish to social platforms. It also enumerates the returned fields (ad_archive_id, page_name, is_active, publisher_platform, snapshot contents), which matters given there is no output schema. It does not cover pagination termination or rate limits.

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-loads purpose, then filters, then return shape, then transport and cost caveats. The return-field enumeration is a long run-on sentence, and the credit/confirm warning is buried at the end, but overall there is little waste.

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 14-parameter, 5-enum tool with no output schema, the description covers the essentials: what comes back, the credit gate, and the transport fallback. Remaining gaps (pagination limits, how trim changes results, exact cost) are minor relative to the schema's full parameter documentation.

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 100%, so the schema already documents all 14 parameters including enums and defaults. The description's only parameter-level addition is the 2-letter language code example, which the schema already states. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'Searches the Meta Ad Library by keyword and returns matching ads.' The keyword-based scope distinguishes it from the company-oriented siblings (facebook_ad_library_company_ads, facebook_ad_library_search_for_companies), but those siblings are never named, so the agent must infer the routing itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives operational guidance (GET for normal requests, POST when the cursor grows too large) and a precondition (requires confirm=true, consumes credits), which is genuinely useful. However, it never says when to choose this tool over the other ad-library search tools or the company-ads variants, so routing guidance is only implied.

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

facebook_ad_library_search_for_companiesSearch for CompaniesA

Searches for companies by name in the Meta Ad Library and returns their page IDs for use with other ad library endpoints. Each result includes page_id, name, category, likes, verification status, and Instagram details like ig_username and ig_followers. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Keyword to search for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which could mislead, but the description proactively clarifies the read-like nature of the POST request ('Read-like POST requests do not publish to social platforms') and adds critical cost/guardrail context ('Potentially consumes paid API credits; requires confirm=true'). This goes beyond annotations. The inconsistency between readOnlyHint=false and the description's read-like claim is not a direct contradiction because the annotation is a conservative default for POST, but the description resolves the ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly packed sentences with zero waste. The purpose and output are front-loaded, followed by the cost/confirmation caveat and the clarification about POST behavior.

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 a filtered search tool with no output schema, the description fully covers what is returned (field list), how the result is used, cost implications, and safety posture. An agent has everything needed to call it correctly.

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 100%, so each parameter is already documented. The description reinforces the 'confirm' requirement and implies the 'query' is the company name, but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource ('Searches for companies by name in the Meta Ad Library') and identifies the output ('returns their page IDs for use with other ad library endpoints'). This clearly distinguishes it from sibling tools like facebook_ad_library_search (which likely searches ads, not companies) and facebook_ad_library_company_ads.

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?

The description implies a discovery-to-retrieval workflow ('page IDs for use with other ad library endpoints'), giving clear context for when to use this tool. However, it does not explicitly name alternatives or state when NOT to use it, leaving some inference to the agent.

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

facebook_ad_library_search_postSearchA

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`query`	No	Keyword to search for
`cursor`	No	Cursor to paginate through results
`status`	No	Status of the ad. Defaults to ACTIVE.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`ad_type`	No	Search for all ads or only political and issue ads
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`country`	No	This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
`payload`	No	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`sort_by`	No	Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
`end_date`	No	Impressions end date. Needs to be in YYYY-MM-DD format.
`language`	No	Language to filter ads on. Needs to be a 2 letter language code, such as EN, ES, or FR.
`media_type`	No	Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.
`start_date`	No	Impressions start date. Needs to be in YYYY-MM-DD format.
`search_type`	No	If you want to search by exact phrase or not
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.9/5.0

Behavior4/5

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

Adds real context beyond the annotations: it warns that the call 'Potentially consumes paid API credits; requires confirm=true' and explicitly resolves the apparent read/write ambiguity by noting 'Read-like POST requests do not publish to social platforms.' This usefully explains why readOnlyHint=false on a de-facto read operation. It does not describe rate limits or pagination semantics beyond the cursor hint.

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-loads purpose, then pagination strategy, then the credit/confirm caveat. Sentences are tight and each carries useful information, though the language-filter sentence restates schema content and could be dropped.

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?

With no output schema, the description compensates by enumerating returned fields (ad_archive_id, page_name, is_active, publisher_platform, snapshot with body/images/videos/cta_text), and it covers the credit cost and confirm requirement. For a 16-parameter tool, it stops short of explaining the payload vs. payload_file vs. body-flag interaction, which an agent would need to choose correctly.

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 100%, so each of the 16 parameters is already documented in the schema, including defaults, enums, and the language 2-letter-code format. The description's mention of language filtering and result fields is largely duplicative, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Searches the Meta Ad Library by keyword and returns matching ads.' It also explains the GET/POST distinction, which is effectively the differentiator from the sibling facebook_ad_library_search, though it never names that sibling explicitly. Clear purpose, near-miss on explicit sibling differentiation.

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 routing guidance: 'Use GET for normal requests. If the cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body' and notes confirm=true is required. It omits when NOT to use this tool (e.g. preferring the company-ads or ad-details siblings for those use cases).

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

facebook_comment_repliesComment RepliesA

Get the replies to a comment. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	The cursor to paginate to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`feedback_id`	Yes	The feedback_id of the comment. Be careful, this is not the comment id. You can get the feedback_id from the /v1/facebook/post/comments endpoint.
`expansion_token`	Yes	The expansion_token of the comment. You can get the expansion_token from the /v1/facebook/post/comments endpoint.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and openWorldHint=true, which could easily mislead an agent into thinking this writes to Facebook. The description explicitly resolves that ambiguity ('Read-like POST requests do not publish to social platforms') and adds credit consumption plus the confirm=true gate. It does not cover rate limits or pagination behavior, so not 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, the core purpose front-loaded, and each remaining clause carries a distinct operational fact (credit cost, confirm gate, no-publish semantics). Zero filler.

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 5-parameter tool with no output schema, the definition covers the essential call-time requirements (confirmation, credits, side-effect-free nature). It leaves the return shape and pagination-via-cursor behavior implicit, which is a minor gap given there is no output schema to fall back on.

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 100% and every parameter is documented, including the subtle feedback_id vs comment id distinction, so the schema already does the heavy lifting. The description adds no parameter-level meaning beyond what is in the schema, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get the replies to a comment') and the platform is carried by the tool name facebook_comment_replies, distinguishing it from instagram_comment_replies / youtube_comment_replies. It stops short of naming the sibling it complements (facebook_comments), so it is clear but not fully differentiated within the Facebook family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a prerequisite (confirm=true) and a cost warning (consumes paid API credits), which is real usage guidance. But it never says when to reach for this tool versus facebook_comments, nor that it must be preceded by fetching feedback_id/expansion_token from the comments endpoint (that context lives only in the schema).

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

facebook_commentsCommentsA

Fetches comments from a Facebook post or reel with cursor-based pagination. Each comment includes id, text, created_at, reply_count, reaction_count, and author details with name and profile_picture. Passing a feedback_id instead of a url significantly speeds up the request. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Facebook post URL (or reel URL)
`cursor`	No	Cursor to get more comments. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`feedback_id`	No	Using feedback_id (instead of url) will really speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post.

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: warns it may consume paid API credits, requires confirm=true, and explains that the read-like POST does not publish to social platforms. This also reconciles the readOnlyHint=false annotation with the fact that it is effectively a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then return fields, then the performance tip, then cost/safety. Four tight sentences, each carrying distinct information with no filler.

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?

With no output schema, spelling out the returned fields (id, text, created_at, reply_count, reaction_count, author name/profile_picture) is valuable, and the credit/confirm/side-effect notes cover the operational risks. 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented (including feedback_id's speed benefit and the cursor). The description only lightly reinforces feedback_id-vs-url and pagination, adding no meaning the schema lacks. Baseline 3 applies.

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 (Fetches) and resource (comments from a Facebook post or reel), and pins the scope with 'cursor-based pagination'. An agent can distinguish it from facebook_comment_replies (top-level vs replies) and from instagram/tiktok comment tools by the platform/resource pairing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Offers a useful in-tool tip (pass feedback_id instead of url to speed up) and cursor-based continuation, but never states when to choose this over siblings like facebook_comment_replies, nor any when-not conditions. Usage is implied rather than routed.

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

facebook_events_event_detailsEvent DetailsA

Get a specific event by its URL or id Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	The ID of the event
`url`	No	The URL of the event
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.6/5.0

Behavior4/5

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

With readOnlyHint=false and idempotentHint=false in the annotations, the description adds genuinely non-derivable behavior: the call may consume paid API credits, demands confirm=true, and that these 'read-like POST requests do not publish to social platforms.' That last clause usefully explains why a non-read-only POST is still effectively a read. It omits error/failure behavior when credits run out.

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?

Three short sentences, front-loaded with the core action, then cost/confirm constraints, then a clarification about the POST semantics. Nothing is redundant, though the newline-joined first two lines could be merged for tighter flow.

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?

Cost and confirmation requirements are covered, but a notable ambiguity is unaddressed: required is empty and both id and url are optional, so the description should say which identifier is preferred or what happens when neither is supplied. No output schema exists, so return values need not be described, but identifier-selection guidance is a real gap.

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 100%, so id, url, account and confirm are already documented in the schema; the description's 'by its URL or id' merely restates it. Baseline 3 applies since the description adds no syntax or selection rule beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a specific event by its URL or id'), which cleanly separates it from the listing/search siblings facebook_events_events and facebook_events_search_events. It stops short of naming those siblings, so an agent must infer the routing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description supplies a hard prerequisite ('requires confirm=true') and a cost warning, which is actionable context. However, it never says when to prefer this tool over facebook_events_events or facebook_events_search_events, and there is no exclusion guidance, so usage is only implied.

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

facebook_events_eventsEventsA

Get the events of a city. Check out this link for an example of where we are getting the data from. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the city's Facebook Events page
`time`	No	The time frame to search for. Defaults to all time
`cursor`	No	The cursor to paginate to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Adds meaningful context beyond the annotations: it discloses credit consumption, the confirm=true gating requirement, and clarifies that the non-read-only POST is 'read-like' and 'does not publish to social platforms' — resolving the apparent tension with readOnlyHint=false. It stops short of describing return shape or pagination behavior.

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?

Purpose is front-loaded in the first sentence, followed by the source example and the operational caveats. It is compact, though the inline example link is somewhat verbose relative to the routing information conveyed.

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 simple fetch tool with no output schema, the description covers purpose, the source, credit cost and the confirm requirement, while annotations carry the safety profile. It is nearly complete, missing only any note on result format or pagination expectations.

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 100%, so all five parameters are already documented in the schema, and the description adds no syntax or format detail beyond restating confirm=true. Baseline 3 is appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope ('Get the events of a city') and grounds it with an example URL of the data source. It is clear what the tool returns, but it does not distinguish itself from the similar sibling facebook_events_search_events, leaving the agent to infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a key usage precondition ('Potentially consumes paid API credits; requires confirm=true'), which tells the agent when a call is safe to make. However, it gives no guidance on when to choose this over alternatives like facebook_events_search_events or facebook_events_event_details.

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

facebook_events_search_eventsSearch EventsA

Search for events by name. You can take a look at the page from Facebook we are getting the data from here Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The query to search for
`cursor`	No	The cursor to paginate to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.5/5.0

Behavior4/5

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

Adds behavior beyond the annotations: discloses that the call 'Potentially consumes paid API credits' and requires confirmation, and clarifies that 'Read-like POST requests do not publish to social platforms.' This resolves the tension between a POST and the destructiveHint=false annotation. It stops short of describing pagination or rate-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, but the inline documentation link is extraneous and the credit/confirm caveats are run together with the publishing note in one sentence. Adequate but not tightly structured.

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?

With no output schema and 100% schema coverage, the description covers the key operational caveats (credits, confirm, no social publishing). It does not explain the returned event shape or how cursor pagination behaves, which is a gap for a search tool.

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 coverage is 100%, so the schema already documents query, cursor, account, and confirm. The description reinforces the confirm=true requirement and the credit-cost rationale, adding marginal value but no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search for events by name'), which is clear on its own. However, it does not differentiate from sibling tools like facebook_events_events or facebook_events_event_details, leaving the agent to infer the boundary between searching, listing, and fetching details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides one concrete precondition ('requires confirm=true') and warns about credit consumption, which is useful routing context. But it gives no guidance on when to prefer this over facebook_events_events or facebook_events_event_details, and no exclusion conditions.

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

facebook_facebook_group_infoFacebook Group InfoA

Fetches the public information shown on a Facebook group's About page, including its description, privacy and visibility, member and activity counts, categories, administrators and moderators when Facebook exposes them, group history, and rules. Provide either url or group_id. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	The Facebook group URL. Group sub-page URLs such as /about work too.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`group_id`	No	The numeric Facebook group ID. Provide this instead of url if you already have it.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false. The description adds non-obvious context the annotations cannot convey: potential paid-credit consumption, the confirm=true gate, and the fact that this is a read-like POST that does not publish to social platforms, plus the 'when Facebook exposes them' caveat on moderators/admins.

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?

Three front-loaded sentences cover returns, input selection, and behavioral caveats with no filler. The long field enumeration in sentence one is dense but informative rather than redundant, since no output schema exists.

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 a tool with no output schema, the description enumerates the returned fields, covers both input alternatives, and discloses the credit/confirm behavior. Nothing an agent needs to select or invoke it correctly appears to be 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 adds a constraint the schema does not encode: url and group_id are alternatives and one should be supplied (the schema marks neither required). That is genuine semantic value beyond the field descriptions.

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 (fetches) and resource (a Facebook group's About-page info), then enumerates the exact fields returned. It is clearly distinguishable from the sibling facebook_facebook_group_posts, which covers posts rather than group metadata.

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 ('Provide either url or group_id') and a precondition (confirm=true). It does not explicitly say when to prefer this over sibling tools such as facebook_facebook_group_posts, so it falls short of full when/when-not guidance.

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

facebook_facebook_group_postsFacebook Group PostsA

Fetches posts from a public Facebook group, limited to 3 posts per page due to API limitations. Each post includes id, text, url, reactionCount, commentCount, publishTime, videoDetails, and topComments. Results are chronological by default. Supports TOP_POSTS, RECENT_ACTIVITY, CHRONOLOGICAL, and CHRONOLOGICAL_LISTINGS with cursor-based pagination. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	The URL of the group
`cursor`	No	The cursor to paginate to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	How to sort the posts. Defaults to CHRONOLOGICAL.
`group_id`	No	The ID of the group

TDQS

A3.9/5.0

Behavior4/5

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

Annotations say readOnlyHint=false, which is unusual for a 'fetch' operation, and the description addresses this directly with 'Read-like POST requests do not publish to social platforms', explaining the apparent mutation. It also discloses the paid-credit consumption and the 3-post-per-page API limit, which are valuable behavioral traits beyond the annotations. However, it does not say whether pagination stops, when the cursor is exhausted, or what the failure mode is if confirm is omitted.

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?

Three short sentences, front-loaded with the core purpose and scope. One sentence ('Potentially consumes paid API credits; requires confirm=true; Read-like POST requests do not publish to social platforms') packs three distinct facts but reads as a run-on list and could be split.

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 6-param, no-output-schema, credit-consuming tool, the description covers the important gaps: the API's 3-post limit, credit cost, the confirm flag, the return fields, and the read-like POST behavior. It omits error handling and cursor exhaustion behavior, but the essentials an agent needs to invoke safely are present.

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 100%, so all six parameters are already documented in the schema. The description reinforces the sort_by enum values (TOP_POSTS, RECENT_ACTIVITY, CHRONOLOGICAL, CHRONOLOGICAL_LISTINGS) and the confirm requirement, but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate.

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?

Starts with a specific verb+resource: 'Fetches posts from a public Facebook group', and clearly distinguishes it from the similarly-named sibling facebook_facebook_group_info by stating it returns post data. An agent can tell what it does immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mentions the constraint 'limited to 3 posts per page', the paid-credit cost, and the confirm=true requirement, but does not name when to use this versus facebook_facebook_group_info or facebook_facebook_group_posts alternatives. The confirm requirement is a strong usage signal, but there is no explicit when-not-to-use guidance.

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

facebook_marketplace_marketplace_itemMarketplace ItemA

Fetches details for a Facebook Marketplace item by item id or Marketplace item URL, including title, description, price, location, condition, photos, seller, and availability flags. Rental listings can include listing_date_text and availability_text from Facebook's Marketplace GraphQL response, for example 'Listed over a week ago' and 'Available now'. creation_time can still be null when Facebook does not expose an exact timestamp. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Facebook Marketplace item id
`url`	No	Facebook Marketplace item URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly=false, idempotent=false, openWorld=true, and the description adds real context beyond them: credit consumption, the confirm=true gate, that POST reads do not publish, that creation_time may be null, and that rental listings surface listing_date_text/availability_text. It stops short of describing rate limits or failure modes, so not 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?

Front-loaded with the purpose and lookup keys, then layers return fields, rental caveats, and cost/auth notes. Dense but every sentence carries information; the middle clause about rental GraphQL fields is slightly heavy but earns its place.

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?

With no output schema, the description carries the return contract itself and does so well, enumerating title, description, price, location, condition, photos, seller, availability flags, plus nullability of creation_time. Combined with the cost/auth disclosure, nothing material is missing for correct invocation.

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 coverage is 100%, so the schema already documents all four parameters including account and confirm. The description only reinforces the id/url lookup basis and restates the confirm gate, adding no syntax or format detail beyond structured fields; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetches details) and resource (Marketplace item) and clarifies the two lookup keys (item id or Marketplace URL). It does not name the sibling it is distinct from (e.g. marketplace_search / marketplace_location_search), so an agent must infer the relationship rather than being routed explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'by item id or Marketplace item URL' and by the confirm=true prerequisite, but there is no explicit when-to-use versus the marketplace search/location-search siblings, nor any when-not condition. Adequate but with clear gaps.

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

facebook_marketplace_marketplace_location_searchMarketplace Location SearchA

Searches Facebook Marketplace locations/cities and returns coordinates you can use with the Marketplace Search endpoint. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Location search query
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.2/5.0

Behavior4/5

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

Adds real value beyond annotations: it warns about paid credit consumption, the confirm=true requirement, and clarifies the read-like POST non-publishing behavior, which explains why readOnlyHint=false despite looking like a read. Does not cover rate limits or error behavior, so not 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler; the output/downstream use is front-loaded and the cost/confirm constraints follow. Every clause carries actionable information.

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 3-param tool with no output schema, the description covers the return value (coordinates), the cost model, and the confirmation requirement. Only minor gaps remain (e.g. what happens if confirm is omitted, coordinate format).

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 100%, so the schema already documents query, account, and confirm. The description restates the confirm=true constraint but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 ('Searches Facebook Marketplace locations/cities') plus the output ('returns coordinates') and its downstream use ('with the Marketplace Search endpoint'). This distinguishes it clearly from the sibling facebook_marketplace_marketplace_search, which consumes those coordinates.

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?

Explains the role in a workflow (prerequisite for Marketplace Search) and states a hard precondition ('requires confirm=true'). It lacks explicit when-not-to-use guidance, but the context is clear enough to route correctly.

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

facebook_marketplace_marketplace_searchMarketplace SearchA

Searches Facebook Marketplace listings by keyword and lat/lng. Each page contains up to 24 listings. Each listing includes creation_time as an ISO 8601 UTC timestamp when Facebook exposes an exact listing timestamp, plus listing_date_text when available; either field can be null. Pass category_id to restrict results to the numeric Facebook Marketplace category ID returned on listing results. Supports pagination with the returned cursor. Pass the cursor value back as-is. The sort and date filters use the same values as Facebook's Marketplace UI. creation_time_descend usually orders the first pages newest first, but Facebook can insert newer listings on later cursor pages. date_listed uses Facebook's calendar-day buckets, so last_24_hours can include listings from the prior calendar day rather than enforcing an exact rolling 24-hour cutoff. For alerting/new-item workflows, continue paging while has_next_page is true and dedupe by listing id. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`lat`	Yes	Latitude for the search location
`lng`	Yes	Longitude for the search location
`query`	Yes	Search keyword
`cursor`	No	Opaque pagination cursor returned from the previous response. Pass it back as-is.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	Facebook Marketplace sort option. creation_time_descend usually orders the first pages newest first, but Facebook can insert newer listings on later cursor pages.
`condition`	No	Condition filter
`max_price`	No	Maximum listing price
`min_price`	No	Minimum listing price
`radius_km`	No	Search radius in kilometers
`category_id`	No	Numeric Facebook Marketplace category ID. Listing results include this value as category_id.
`date_listed`	No	Facebook Marketplace date filter. Uses the same calendar-day buckets as the UI, so last_24_hours can include listings from the prior calendar day.
`availability`	No	Availability filter
`delivery_method`	No	Delivery filter

TDQS

A4.3/5.0

Behavior5/5

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

With annotations declaring readOnlyHint=false, this description does real work: it warns that calls potentially consume paid API credits and require confirm=true, and explains that the read-like POST does not publish to social platforms. It also discloses that creation_time/listing_date_text can be null, that creation_time_descend is unstable across cursor pages, and that date_listed uses calendar-day buckets.

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 purpose and pagination essentials, then caveats. Dense with useful facts and little waste, though the sentences on sort_by and date_listed restate schema text somewhat, making it longer than strictly necessary.

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 a 15-parameter tool with no output schema, the description covers the key return fields (creation_time, listing_date_text, cursor, has_next_page), pagination mechanics, and behavioral caveats. An agent has enough to page, dedupe, and avoid credit surprises without opening anything else.

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% (baseline 3), and the description still adds meaning: category_id is the numeric FB category ID echoed back in results, cursor must be passed through unchanged, and sort_by/date_listed carry non-obvious server-side behavior. It does not add semantics for the simple filter params (condition, price, radius), which the schema already covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Searches Facebook Marketplace listings') and the key scoping inputs (keyword, lat/lng). It is clearly a search tool, though it never explicitly distinguishes itself from sibling facebook_marketplace_marketplace_location_search or facebook_marketplace_marketplace_item, leaving that routing to inference.

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 strong operational guidance: pass cursor back as-is, continue paging while has_next_page is true and dedupe by listing id for new-item workflows, and confirms that sort/date filters use the same values as the UI. It stops short of stating when to prefer this tool over the location-search or item siblings.

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

facebook_postPostA

Retrieves a single public Facebook post or reel by URL. Returns post_id, like_count, comment_count, share_count, view_count, description, creation_time, and author details, including the author handle when Facebook exposes a vanity profile URL. For some reels, Facebook does not expose the same view count on the individual post page that it shows on the profile Reels grid. This value can be null or lower than the public Reels badge. If you need the public Reel badge count, call /v1/facebook/profile/reels with the author URL and match the reel by post_id. For video posts, includes video sd_url, hd_url, thumbnail, and length_in_second. Optionally fetches comments and transcript via get_comments and get_transcript parameters. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the post to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4/5.0

Behavior4/5

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

Adds real behavioral context beyond the annotations: it consumes paid API credits, requires confirm=true, is a read-like POST that does not publish to social platforms, and warns that reel view_count may be null or lower than the profile badge. This resolves the apparent tension of readOnlyHint=false with the POST verb. It does not address caching/rate-limit behavior (though the schema covers caching).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return fields, but the middle is dense with reel-badge caveats, and the closing mention of non-existent get_comments/get_transcript parameters spends words on something an agent cannot act on. Reasonable size for the information, but with wasted and misleading content.

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?

With no output schema, the description carries the return-shape burden and does so by listing post_id, engagement counts, timestamps, and video fields, plus the vanity-URL caveat and the reel-count workaround. The only gap is the dangling reference to optional parameters that the schema does not actually expose.

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 100%, so the baseline is 3. The description restates the confirm requirement but adds no format or syntax detail for url, account, or cache_max_age. It also references get_comments and get_transcript parameters that do not exist in the input schema, which weakens rather than strengthens parameter clarity.

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 ('Retrieves a single public Facebook post or reel by URL') and enumerates the returned fields, so it is immediately distinguishable from siblings like facebook_profile_posts and facebook_profile_reels. An agent can tell what this tool yields without opening the schema.

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 a concrete routing rule: when the public Reel badge count is needed, call facebook_profile_reels and match by post_id. It also notes confirm=true is required for credit-consuming calls. However it does not cover when this tool should be preferred over, e.g., facebook_comments for comment retrieval.

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

facebook_profileProfileA

Retrieves public Facebook page details including category, address, email, phone, website, services, priceRange, rating, likeCount, talkingAboutCount, and followerCount. talkingAboutCount is nullable and only returned when Facebook exposes it publicly. Also returns adLibrary status with the page's ad activity and pageId. Optionally includes businessHours when get_business_hours is set to true. Contact fields come from the submitted public profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. If Facebook shows an 18+ content gate, the response is still 200 with account_status: "age-restricted" and isPrivate: true. If Facebook shows a private content gate, the response is still 200 with account_status: "private" and isPrivate: true. If the page is not found, the response is 404 with accountDoesNotExist: true and isPrivate: false. Set include_gated_profile=true to also return limited public fields (such as id, name, category, likeCount, profilePicSmall, and links) when a profile is gated or age-restricted. This option only affects gated/age-restricted profiles — public profiles still return the normal full response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Facebook profile URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)
`get_business_hours`	No	Get the business's hours
`include_gated_profile`	No	When true, returns limited public fields for gated or age-restricted profiles. Ignored for normal public profiles — those still return the full response.

TDQS

A4.1/5.0

Behavior5/5

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true) by disclosing credit consumption, the confirm=true requirement, the exact 404/200 status semantics for gated, age-restricted, and missing pages, and that read-like POSTs do not publish. This is rich behavioral context an agent cannot derive from the schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the returned fields, but the body is dense and repetitive — the gating/age-restriction behavior is re-explained across several sentences and the include_gated_profile caveat is stated twice. Roughly half the length would carry the same information.

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 a 6-parameter tool with no output schema, the description covers return fields, nullability, error/gate status codes, credit cost, confirmation, and caching behavior. An agent has everything needed to invoke it correctly and interpret responses.

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 100%, so the baseline is 3. The description clarifies that include_gated_profile only matters for gated profiles and that get_business_hours is optional, but these points largely restate the schema rather than adding new meaning beyond it.

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 (retrieves) and resource (public Facebook page details) and enumerates the exact fields returned (category, address, email, phone, rating, likeCount, etc.). This clearly separates it from siblings like facebook_profile_posts, facebook_profile_photos, and facebook_profile_reels without needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description thoroughly explains the conditions under which options apply (include_gated_profile only affects gated/age-restricted profiles, contact fields come from the submitted profile, caching semantics), but it never routes the agent between this tool and sibling profile-retrieval tools. Usage is implied by the field list rather than explicitly guided.

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

facebook_profile_eventsProfile EventsA

Get the events of a public Facebook page Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the public Facebook page
`cursor`	No	The cursor to paginate to get more events
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: it warns that the call 'Potentially consumes paid API credits; requires confirm=true' and clarifies that 'Read-like POST requests do not publish to social platforms.' This explains the confirm gate and mitigates the non-readOnly hint, which is genuinely helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero waste, front-loading the core action and then appending the critical operational note about credits and confirm. Every sentence earns its place.

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 tool with no output schema and full annotation coverage, the description covers the essential behavioral note (credit cost, confirm requirement) and clarifies the POST-vs-publish distinction. It could mention pagination via cursor or return format, but given annotations and schema completeness, it is largely sufficient.

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 coverage is 100%, so the schema already documents all four parameters (url, cursor, account, confirm). The description adds a note about confirm=true and paid credits but doesn't provide additional syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: 'Get the events of a public Facebook page', which is clear and distinct from siblings like facebook_events_events or facebook_profile_posts. It could be sharper about scope (upcoming vs past events, single page vs multiple), but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying 'public Facebook page' and mentioning confirm=true for credit consumption, but it doesn't state when to use this tool vs alternatives like facebook_events_events or facebook_events_search_events. No exclusions or alternative routing are given.

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

facebook_profile_photosProfile PhotosA

Fetches photos from a public Facebook page with pagination support. Each photo includes photo_id, accessibility_caption, viewer_image with uri, height, and width, plus a thumbnail and direct url. Pagination requires passing both next_page_id and cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Facebook page URL
`cursor`	No	To paginate through to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`next_page_id`	No	To paginate through to the next page

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already flag readOnlyHint=false/openWorldHint=true/destructiveHint=false. The description adds real value beyond them: credit consumption, the confirm=true gate, and the two-field pagination requirement (next_page_id AND cursor). It also reconciles the readOnlyHint=false by explaining read-like POSTs do not publish.

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 purpose, then returns, then pagination, then cost/confirmation. The middle enumeration of return fields is slightly dense but justified because no output schema exists. No filler sentences.

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?

With no output schema, the description correctly documents the returned fields (photo_id, accessibility_caption, viewer_image, thumbnail, url), plus pagination and credit/confirm behavior. An agent has everything needed to call it correctly.

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 baseline is 3. The description exceeds it by explaining the pagination contract — both next_page_id and cursor must come from the previous response — which the schema's one-line param descriptions do not convey.

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 (fetches) and resource (photos from a public Facebook page), which cleanly distinguishes it from sibling tools like facebook_profile_posts, facebook_profile_reels, and facebook_profile. The added note that it hits a public page gives scope immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides operational context (consumes paid credits, requires confirm=true) but never states when to use this versus alternatives such as facebook_profile_posts or facebook_profile_reels. Usage is implied by the resource name rather than explicitly routed.

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

facebook_profile_postsProfile PostsA

Returns publicly visible Facebook profile posts, limited to 3 posts per page due to API limitations. Each post includes id, text, url, reactionCount, commentCount, publishTime, videoDetails with sdUrl, hdUrl, and thumbnailUrl, plus topComments. Accepts either a url or pageId parameter, where pageId is faster. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Facebook profile URL
`cursor`	No	To paginate through the posts
`pageId`	No	Facebook profile page id
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.4/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: a 3-post-per-page API ceiling, paid-credit consumption, a mandatory confirm=true, and a reconciliation of why a read operation is annotated readOnlyHint=false (read-like POST that does not publish). This is exactly the kind of context annotations cannot convey.

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-loads the core purpose, then the per-post field list, parameter choice, and cost caveat. Dense but every sentence carries information; the field enumeration is slightly verbose but useful given no output schema.

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?

With no output schema, the description supplies the return shape (id, text, url, counts, publishTime, videoDetails URLs, topComments) and the pagination limit, plus the credit/confirm requirement. 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 adds value by noting url and pageId are alternatives and that pageId is faster. It does not restate the confirm/cursor semantics, which the schema already covers.

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 (returns publicly visible Facebook profile posts) with clear scope, and the enumerated return fields distinguish it from siblings like facebook_profile and facebook_post. An agent can tell what this returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the usage context (fetch a profile's posts) and gives a parameter-choice hint ('pageId is faster'), but names no alternatives and states no when-not conditions versus facebook_profile_posts-adjacent tools. Usage is implied rather than defined.

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

facebook_profile_reelsProfile ReelsA

Fetches up to 10 reels per request from a public Facebook page. Each reel includes id, url, view_count, description, creation_time, video_url, thumbnail, play_time_in_ms, and music details. Pagination requires passing both next_page_id and cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Facebook page URL
`cursor`	No	To paginate through to the next page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`next_page_id`	No	To paginate through to the next page

TDQS

A4.4/5.0

Behavior5/5

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

Annotations alone (readOnlyHint=false, idempotentHint=false) would look alarming, and the description resolves it by disclosing that it consumes paid API credits, requires confirm=true, and that 'read-like POST requests do not publish to social platforms.' It also enumerates the returned field set, which matters since there is no output schema.

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-loads what it fetches, then return shape, pagination, and cost/auth constraints. The long inline field enumeration is slightly bulky but each clause carries concrete information an agent needs.

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?

With no output schema, the description supplies the return field list, plus pagination mechanics, credit cost, and the confirm requirement. Nothing essential to calling 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 baseline is 3. The description exceeds it by clarifying that pagination requires BOTH next_page_id and cursor from the previous response, a constraint the individual schema fields ('To paginate through to the next page') do not convey.

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 (fetches), resource (reels), source (a public Facebook page), and scope (up to 10 per request). An agent can distinguish it from facebook_profile_posts and facebook_profile_photos without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It describes operational conditions (public page, confirm=true, credit consumption) but never says when to prefer this tool over siblings like facebook_profile_posts or instagram_reels. Usage is implied by the resource name rather than explicitly guided.

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

facebook_transcriptTranscriptA

Extracts the transcript text from a Facebook video post or reel. Returns the transcript as a single text string with line breaks. Only works on videos under 2 minutes in length. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Facebook post URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.8/5.0

Behavior4/5

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

Adds context the annotations cannot convey: potential paid-credit consumption, the confirm=true gate, and the explanation that read-like POSTs do not publish to social platforms, which reconciles the readOnlyHint=false annotation. It does not mention rate limits or failure behavior on private/age-gated videos.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what is returned and its shape, then the hard limit, then the cost/gate caveat. No sentence is padding.

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?

With no output schema, the description usefully specifies the return format (single text string with line breaks) and the main preconditions. It leaves the multi-account/cache selection behavior entirely to the schema, which is reasonable given 100% coverage but leaves the credit-confirmation workflow slightly implicit.

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 100%, so url, account, confirm, and cache_max_age are already documented including the caching/credit mechanics. The description restates the confirm requirement but adds no syntax or format detail beyond the structured fields, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Extracts the transcript text from a Facebook video post or reel') plus the platform, which cleanly separates it from the many sibling *_transcript tools. It never names those siblings (tiktok_transcript, instagram_transcript, facebook_ad_library_ad_transcript), so differentiation is by platform inference rather than explicit routing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete applicability constraints – videos must be under 2 minutes, confirm=true is required, credits may be consumed – which tells the agent when the call will fail. It stops short of stating when to prefer this over other transcript tools or what to do when the video exceeds the length limit.

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

github_activityActivityA

Retrieves GitHub profile contribution activity for a user from the public profile activity timeline. Defaults to the current year when year is not provided. Results come back one month at a time in the activity array. Pass cursor from the previous response to page backward through the year. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub user URL, e.g. https://github.com/kentcdodds.
`year`	No	When provided, returns profile contribution activity for that year. Defaults to the current year.
`cursor`	No	Cursor from the previous response. Pages backward by month through the selected year.
`handle`	No	GitHub handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations mark this as non-read-only, non-idempotent and open-world, but the description adds real context the annotations cannot: it consumes paid API credits, requires confirm=true, and clarifies the read-like POST does not publish to social platforms. This materially helps an agent understand cost and side-effect risk 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-loads the core purpose, then layers defaults, pagination and cost constraints in short sentences. Mostly tight, though the trailing sentence about read-like POSTs and social platforms reads as a generic disclaimer that is slightly tangential to the GitHub activity use case.

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?

With no output schema, the description usefully describes the return shape (activity array, one month at a time) alongside defaults, pagination and the credit/confirm requirements. An agent has enough to invoke it correctly, though the absence of any explicit alternative-tool routing leaves a small gap.

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 parameter baseline is 3, but the description goes further by explaining the cursor's paging semantics and the monthly granularity of the activity array, which is return-shape information not encoded in the schema. One parameter's role (account) is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Retrieves GitHub profile contribution activity ... from the public profile activity timeline,' and grounds it as a per-user, per-year timeline. It is clear on its own, though it does not explicitly distinguish itself from the close sibling github_contributions, leaving some ambiguity an agent must resolve by inspecting both schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives useful operational guidance: year defaults to the current year, results are paginated one month at a time, and you pass the cursor from the previous response to page backward. It also flags the confirm=true prerequisite. However, it never states when to prefer this tool over github_contributions or the other github_* siblings, so selection guidance is only implied.

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

github_contributionsContributionsA

Retrieves the public GitHub contribution graph for a user and year, including total contributions and daily contribution counts/intensity. Pass github handle, or a full GitHub profile url. Defaults to the current year when year is not provided. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub profile URL
`year`	No	Contribution graph year. Defaults to the current year.
`handle`	No	GitHub handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds genuinely new behavioral context: that the call can consume paid API credits, that confirm=true is mandatory, and that this read-like POST does not publish to social platforms - directly explaining why a read-style operation is flagged non-read-only. It doesn't cover rate limits or failure modes, so not a full 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?

Three tight sentences, front-loaded with the payload description followed by input rules and then the cost/confirm caveat. The final clause ("Read-like POST requests do not publish to social platforms") is slightly elliptical, but nothing is wasted.

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 credit-consuming fetch tool with no output schema, the description covers the returned data shape, the input forms, and the payment/confirmation requirement. What remains unstated - pagination, error behavior, credential resolution for account - is minor but not trivial.

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 100%, so every parameter is already documented in the schema. The description only restates that handle and url are alternatives and that year defaults to the current year, which the schema already says. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("Retrieves the public GitHub contribution graph for a user and year") and enumerates the payload (totals plus daily counts/intensity). It is clear enough to separate this from generic profile tools, but it never explicitly names competing siblings like github_activity or github_user, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives input guidance (pass a handle or a full profile URL, year defaults to current) and a hard prerequisite (confirm=true, credits consumed), which is useful. However, there is no explicit when-to-use versus when-not, and no routing to an alternative for related GitHub data, so usage is only implied.

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

github_followersFollowersA

Retrieves public GitHub followers for a user. Each follower includes login, avatar, user URL, type, and GitHub IDs. Pass username, handle, or a full GitHub user url. Supports cursor pagination. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub user URL, e.g. https://github.com/torvalds.
`cursor`	No	Cursor from the previous response. Defaults to 1.
`handle`	No	GitHub username/handle of the user you want the followers for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) already frame this as a non-cached, non-read operation, and the description adds context the annotations cannot: it consumes paid API credits, requires confirm=true, supports cursor pagination, and clarifies that the read-like POST does not publish to social platforms. That clarification explains the surprising readOnlyHint=false rather than contradicting it.

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?

Three tight sentences with the resource and return shape front-loaded, followed by input forms, pagination, and the credit/confirm caveat. Every sentence carries information; the final clause about social platforms is slightly tangential to a GitHub tool but still earns its place as a safety clarification.

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?

With no output schema, the description compensates by listing the returned fields (login, avatar, user URL, type, GitHub IDs) and documents pagination and the confirmation gate. For a 5-parameter, zero-required tool it is nearly complete; only the exact pagination termination/cursor behavior is left unspecified.

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 description coverage is 100%, so the schema already defines each parameter; the baseline is 3. The description adds meaning beyond the schema by framing handle/url as alternative input forms and by surfacing the confirm requirement operationally, which an agent skimming only property docs might miss.

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+resource ('Retrieves public GitHub followers for a user') and goes on to enumerate the returned fields, so the agent knows exactly what it gets. It is clearly separable from the sibling github_following (reverse direction) without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says how to supply the target ('Pass username, handle, or a full GitHub user url') and states the confirm=true prerequisite, which is real invocation guidance. However, it never says when to prefer this over github_following or other github_* siblings, and no exclusions are given, so usage is only implied.

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

github_followingFollowingA

Retrieves public accounts followed by a GitHub user. Each account includes login, avatar, profile URL, type, and GitHub IDs. Pass username, handle, or a full GitHub profile url. Supports cursor pagination. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub profile URL
`cursor`	No	Cursor from the previous response. Defaults to 1.
`handle`	No	GitHub handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

With annotations present, the description adds real value beyond them: it discloses that the call consumes paid API credits, requires confirm=true, and explains the otherwise-confusing readOnlyHint=false by stating that read-like POST requests do not publish to social platforms. It also notes cursor pagination. It does not cover rate limits or failure behavior, keeping it short of 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then return fields, accepted inputs, pagination, and the cost/confirm constraint in four tight sentences with no filler. Every sentence carries distinct information.

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?

There is no output schema, but the description compensates by enumerating the returned fields (login, avatar, profile URL, type, GitHub IDs) and covers pagination, credit cost, and the confirm requirement. An agent has everything needed to call this correctly.

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 100%, so the schema already documents all five parameters, making 3 the baseline. The description adds only marginal meaning by listing acceptable identifier forms (username/handle/full profile url) and noting cursor pagination, and it mentions a 'username' form that does not map cleanly onto any named schema property.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Retrieves public accounts followed by a GitHub user', and even enumerates the returned fields. The wording inherently separates it from the sibling github_followers (following vs. followers), though it never names that sibling explicitly, so the distinction depends on careful reading rather than an explicit contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied by the purpose ('accounts followed by'), but there is no when-to-use guidance and no mention of the obvious alternative, github_followers. It does supply invocation prerequisites (confirm=true, paid credits), which is helpful but is not routing guidance.

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

github_pull_requestsPull RequestsA

Searches public GitHub pull requests authored by a user using GitHub's public search index. Pass username, handle, or url. Optional since and until filters use YYYY-MM-DD created dates. Results include the PR title, repo, state, created_at, and url, sorted by newest created first. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`since`	No	Only return pull requests created on or after this date. Use YYYY-MM-DD.
`until`	No	Only return pull requests created on or before this date. Use YYYY-MM-DD.
`cursor`	No	Cursor from the previous response. Defaults to 1.
`handle`	Yes	GitHub username/handle of the user you want pull requests for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Despite readOnlyHint=false, the description usefully discloses that this consumes paid API credits, requires confirm=true, and that read-like POSTs do not publish to social platforms — real context beyond the annotations. It also reveals result contents and sort order. It stops short of describing pagination/cursor behavior.

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 purpose, then filters, then result shape, then the credit/confirm caveat. Four tight sentences with no filler, though the credit/confirm sentence could be slightly more integrated.

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?

With no output schema, the description helpfully enumerates returned fields (title, repo, state, created_at, url) and sort order, and covers the credit/confirm requirement. Only cursor/pagination semantics are unaddressed, a minor gap for this tool.

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 100%, so the baseline is 3. The description restates date format (YYYY-MM-DD) already documented in the schema and notes identity can be a username/handle/url, but adds little operational detail beyond what the schema already carries.

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 ('Searches public GitHub pull requests authored by a user'), plus scope ('public search index') and the input identity (username/handle/url). This is clearly distinguishable from siblings like github_activity, github_contributions, and github_repositories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('authored by a user', use since/until to filter), so an agent can infer the scenario. However, it gives no explicit when-to-use vs alternatives (e.g., github_activity or github_contributions for other GitHub signals) and no exclusions, leaving routing to inference.

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

github_repositoriesRepositoriesA

Retrieves a user's public repositories with repo metadata like description, language, stars, forks, topics, license, visibility, default branch, and timestamps. Pass username, handle, or url. Supports pagination with cursor, plus GitHub's type, sort, and direction parameters. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub user URL, e.g. https://github.com/kentcdodds.
`sort`	No	Sort by created, updated, pushed, or full_name. Defaults to updated.
`type`	No	Repository type. Defaults to owner. GitHub also supports all and member.
`cursor`	No	Cursor from the previous response. Defaults to 1.
`handle`	No	GitHub username/handle of the user you want the repositories for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`direction`	No	Sort direction: ascending or descending.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorld=true), and the description adds non-derivable behavior: that calls may consume paid API credits, that confirm=true is required, and that the read-like POST does not publish to social platforms. It stops short of covering error handling, failure modes, or rate-limit specifics, so it is strong but not exhaustive.

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 core action and returned fields, then a second paragraph for identity inputs and the cost/confirm caveat. Two sentences carry the load with no filler; the final sentence about social-platform publishing is slightly defensive but still earns its place as behavior disclosure.

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 8-parameter, no-required-param, no-output-schema list tool, the description covers the returned metadata, the identity inputs, pagination, and the credit/confirm constraint. Combined with a fully documented schema and existing safety annotations, an agent has everything needed to call it correctly.

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 100%, so every parameter (url, handle, account, cursor, type, sort, direction, confirm) is already documented in the schema with enums and defaults. The description restates the identity inputs and pagination but adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves a user's public repositories') and enumerates the returned metadata (description, language, stars, forks, topics, license, visibility, default branch, timestamps). The scope clearly separates it from the singular github_repository and from github_user, but the description never names those siblings, so it stops just short of explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent how to supply an identity ('Pass username, handle, or url') and that pagination uses a cursor, which implies usage. However it never states when to choose this over github_repository, github_user, or github_trending_repositories, and gives no prerequisites or exclusions, so selection guidance must be inferred from the name.

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

github_repositoryRepositoryA

Retrieves public metadata for one GitHub repository, including owner, description, language, stars, forks, topics, license, visibility, default branch, open issues, and timestamps. Pass a full GitHub repository url. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	GitHub repository URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds meaningful context beyond them: it consumes paid API credits, requires confirm=true, and clarifies the read-like POST does not publish to social platforms. This credit/cost disclosure is genuinely useful.

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 core purpose and returned fields, then the URL instruction, then cost/permission notes. Efficient and well-ordered, with no filler, though the final sentence is slightly tangential.

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 tool with no output schema, listing returned fields is a helpful completeness measure, and cost + confirm requirements are disclosed. An agent has what it needs to invoke it correctly; only the absent sibling routing keeps it short of full marks.

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 100%, so all three parameters (url, account, confirm) are already documented in the schema. The description only nudges the url format ('full GitHub repository url'), adding marginal value over what the schema provides — baseline 3.

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 (Retrieves) and resource (public metadata for one GitHub repository), and enumerates the returned fields (owner, stars, forks, license, etc.). The singular 'one repository' distinguishes it clearly from the sibling github_repositories list tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides one actionable instruction ('Pass a full GitHub repository url') and implies single-repo scope, but never names the alternative (github_repositories, github_user) or states when-not to use it. Usage is implied rather than explicit.

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

github_trending_developersTrending DevelopersA

Scrapes GitHub's public Trending developers page. Returns ranked developers with username, name, public profile URL, avatar, and the popular repository GitHub shows for that developer when available. Use language for paths like javascript or python and since for daily/weekly/monthly. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`since`	No	Trending range: daily, weekly, or monthly. Defaults to daily.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	Optional trending coding language, e.g. javascript, python, or go.

TDQS

A4/5.0

Behavior4/5

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

With annotations present, the description still adds meaningful context: it discloses that calls potentially consume paid API credits, that confirm=true is required, and it explains the read-like POST nature so the agent understands why readOnlyHint is false. This goes beyond what the annotations alone convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose and return shape first, then usage/value notes, then the credit and confirm constraint. Every sentence carries information and nothing is padded.

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?

No output schema exists, but the description enumerates expected return fields, covers all parameters via schema, and states the credit/confirm behavioral requirement. It is close to complete, though the pagination/ranking behavior and any rate limits are unstated.

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 coverage is 100%, so all four parameters are already documented in-schema, including examples for language and the enum for since. The description's restatement of language/since values adds marginal value, so the baseline 3 applies.

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 (scrapes) and resource (GitHub's public Trending developers page), and enumerates the returned fields (username, name, profile URL, avatar, popular repo). This clearly separates it from the sibling github_trending_repositories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives value hints ('Use language for paths like javascript or python and since for daily/weekly/monthly') but these are parameter examples rather than when-to-use routing. It never says when to pick this over github_trending_repositories or any other sibling, leaving usage implied.

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

github_trending_repositoriesTrending RepositoriesA

Scrapes GitHub's public Trending repositories page. Returns ranked repositories with public URLs, descriptions, language, star/fork counts, stars for the selected range, and built-by users when GitHub shows them. Use language for paths like JavaScript or Python, since for daily/weekly/monthly, and spoken_language_code for GitHub's spoken language filter. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`since`	No	Trending range: daily, weekly, or monthly. Defaults to daily.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	Optional coding language, e.g. javascript, python, or go.
`spoken_language_code`	No	Optional spoken language code filter, e.g. en.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds genuinely useful context beyond them: it consumes paid API credits, requires confirm=true, and clarifies that the read-like POST does not publish to social platforms. It also enumerates returned fields, which the absent output schema cannot.

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 core action and return contents, then parameter hints, then the credit/confirm warning. Every sentence carries information, though the social-platform disclaimer is slightly awkwardly worded for the audience.

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?

Covers the important gaps for a zero-required-param scraper with no output schema: it lists the returned fields, discloses credit consumption and the confirm requirement, and explains the read-like POST behavior. An agent has everything needed to call it correctly.

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 coverage is 100%, so the schema already documents all five parameters including the since enum and defaults. The description's restatement of language/since/spoken_language_code usage adds marginal value but no syntax or format detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Scrapes GitHub's public Trending repositories page'. The name and description make the target obvious, though the description never explicitly contrasts itself with the close sibling github_trending_developers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Most of the guidance is parameter-level ('use language for..., since for..., spoken_language_code for...') rather than when-to-use vs alternatives. There is no statement of when this tool is preferable to github_repositories or github_trending_developers, so usage is only implied.

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

github_userUserA

Retrieves public GitHub user details including name, bio, avatar, company, location, blog, follower counts, public repo counts, and account timestamps. Pass username, handle, or a full GitHub user url. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	GitHub user URL, e.g. https://github.com/torvalds.
`handle`	No	GitHub username/handle of the user you want the details for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which would otherwise puzzle an agent calling a simple profile lookup; the description resolves this by disclosing that it is a "read-like POST" that does not publish to social platforms. It also adds two genuinely non-schema facts: possible paid credit consumption and the confirm=true gate. It omits rate-limit or failure behavior, keeping 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?

Three sentences, front-loaded with the payload contents before operational caveats. Every sentence carries information, and the credit/confirm note is placed after the core purpose. The read-like-POST clarification is slightly boilerplate but earns its place given readOnlyHint=false.

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?

There is no output schema, but the description enumerates the returned fields, which compensates. It covers the credit cost and confirm requirement, and the identifier input forms. It leaves gaps around what happens without confirm and whether the identifier parameters are alternatives, so it is strong but not exhaustive.

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 100%, so all four parameters are already documented by the schema, making 3 the baseline. The sentence "Pass username, handle, or a full GitHub user url" mostly restates the url/handle descriptions and does not clarify the alternative semantics of the account parameter or whether url/handle are mutually exclusive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Retrieves public GitHub user details") and enumerates the returned fields (name, bio, avatar, company, location, blog, follower counts, repo counts, timestamps). The scope is unmistakably the profile-lookup tool rather than the sibling github_repositories or github_followers. It stops short of explicitly naming a sibling to differentiate against, so it lands just under a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent what to pass (username, handle, or full GitHub url) and that confirm=true is required, which is actionable. However, it never contrasts with alternatives such as github_followers, github_contributions, or github_repositories, and gives no when-not guidance. Usage is implied rather than instructed.

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

google_ad_library_ad_detailsAd DetailsA

Retrieves detailed information about a specific Google ad including advertiserId, creativeId, format, firstShown, lastShown, and overallImpressions. When Google publishes political-ad transparency data, spend contains the currency and amount bounds, while targeting contains included and excluded age, gender, and location criteria. Targeted locations include their Google criterion ID, display name, full name, and country codes. Optional fields are null when Google does not publish them. Returns creativeRegions, regionStats with per-region impression data, and variations with destinationUrl, headline, description, and imageUrl. Text extraction uses OCR, so accuracy may vary. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The url of the ad
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.2/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing credit consumption, the mandatory confirm=true, cache-vs-live behavior, that optional fields are null when unpublished, and that text extraction uses OCR so accuracy varies. The read-like POST/no-social-publish clarification reconciles the non-read-only annotation with the actual effect.

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 core purpose, then layers conditional details (political-ad spend/targeting, nullability, return structure, OCR caveat) in an orderly sequence. Slightly dense and field-list-heavy, but nearly every clause carries information an agent needs.

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?

With no output schema available, the description compensates by describing the return shape in detail: spend currency/amount bounds, targeting criteria with Google criterion IDs, creativeRegions, regionStats per-region impressions, and variations (destinationUrl, headline, description, imageUrl). That is sufficient for a 4-parameter tool.

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 100%, so the schema already documents url, account, confirm, and cache_max_age. The description reinforces confirm=true and credit cost but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 (retrieves) and resource (detailed information about a specific Google ad), then enumerates the concrete fields returned (advertiserId, creativeId, format, firstShown, lastShown, overallImpressions). An agent can distinguish this from google_ad_library_company_ads, which lists a company's ads rather than one ad's details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides prerequisites rather than routing guidance: it warns that the call consumes paid credits, requires confirm=true, and notes cache_max_age behavior. However it never states when to use this over sibling advertiser/company/transcript tools or what to do if the ad URL is unknown, so selection guidance is only implied.

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

google_ad_library_advertiser_searchAdvertiser SearchA

Searches the Google Ad Transparency Library for advertisers by name. Returns a list of matching advertisers with their name, advertiser_id, and region, plus a list of associated website domains. Use the returned advertiser_id to look up a company's ads. Defaults to US when region is not passed, so pass a 2-letter country code like AU or CA when searching for advertisers in another region. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The query to search for
`region`	No	2-letter country code to search in. Defaults to US when omitted.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.2/5.0

Behavior4/5

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

Annotations mark readOnlyHint=false, openWorldHint=true, idempotentHint=false, so the safety profile is partly covered; the description adds meaningful context beyond them by disclosing paid credit consumption, the confirm=true requirement, and that this read-like POST does not publish to social platforms. No contradiction with annotations.

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?

Four sentences, front-loaded with purpose then result then calling guidance then cost/safety caveats. Each sentence earns its place, though the region-default sentence partly duplicates the schema's region description.

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?

With no output schema, the description steps in to describe the return payload (name, advertiser_id, region, associated domains), and it covers the credit/confirm gating that governs correct invocation. Nothing essential for a correct call is missing.

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 100%, so the schema already documents query, region, account, and confirm. The description reinforces the region default and confirm requirement but adds no syntax or format detail beyond what the schema states, so baseline 3 applies.

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 (searches) plus resource (Google Ad Transparency Library / advertisers by name) and clearly distinguishes itself from sibling tools like google_ad_library_company_ads and google_ad_library_ad_details by positioning itself as the entry point that yields advertiser_id.

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?

Explicitly tells the agent what to do with the result (use advertiser_id to look up a company's ads) and gives a concrete rule for region handling with examples. It doesn't name the sibling alternative explicitly, but the routing intent is unambiguous.

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

google_ad_library_company_adsCompany AdsA

Fetches public ads for a company from the Google Ad Transparency Library by domain or advertiser_id. Each ad includes advertiserId, creativeId, format, adUrl, advertiserName, domain, firstShown, and lastShown. Costs 25 credits per request when get_ad_details=true; without it, only advertiserId and creativeId are returned at 1 credit. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`topic`	No	The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU'
`cursor`	No	Cursor to paginate through results
`domain`	No	The domain of the company
`format`	No	Ad format to search for.
`region`	No	The region to search for. Defaults to anywhere
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`end_date`	No	End date to search for. Format: YYYY-MM-DD
`platform`	No	Platform to search for.
`start_date`	No	Start date to search for. Format: YYYY-MM-DD
`advertiser_id`	No	The advertiser id of the company
`get_ad_details`	No	Set to true to get the ad details. Will cost 25 credits.

TDQS

A4.3/5.0

Behavior4/5

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

Goes beyond annotations by disclosing the credit cost model, the required confirm=true gate, and what the response contains at each cost tier. It also clarifies that read-like POSTs do not publish to social platforms, resolving the apparent tension with readOnlyHint=false. No rate-limit or failure behavior is described, but the cost/auth disclosure is substantive.

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?

Three sentences, front-loaded with purpose then cost/return semantics then safety note. The enumerated return-field list is slightly long but each item is informative and no sentence is redundant.

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?

With no output schema, the description usefully enumerates return fields and states the cost/confirmation contract, which is what an agent needs before committing credits. Pagination via cursor and the political-topic/region coupling are left to the schema, which documents them adequately.

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; the description earns above that by explaining what get_ad_details actually changes in the returned payload and tying credit cost to the parameter choice, which the schema description only states as 'Will cost 25 credits.'

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 (fetches), resource (public ads for a company), and data source (Google Ad Transparency Library), plus the two lookup keys (domain or advertiser_id). This clearly separates it from google_ad_library_ad_details and google_ad_library_advertiser_search.

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?

Explains the key cost tradeoff that governs selection: get_ad_details=true costs 25 credits and returns rich fields, while omitting it returns only advertiserId and creativeId at 1 credit. It does not, however, explicitly route the agent between this tool and the sibling google_ad_library_advertiser_search or ad_details tools.

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

google_searchSearchA

Performs a Google search and returns organic results with url, title, and description for each result. Supports an optional region parameter (2-letter country code) to get localized results from a specific country. Pages 1 through 11 are supported; requests for page 12 or greater return a 400 response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number to retrieve. Must be between 1 and 11; page 12 or greater returns a 400 response.
`query`	Yes	Search query
`region`	No	2 letter country code, ie US, UK, CA, etc This will show results from that country
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`date_posted`	No	Date posted

TDQS

A4/5.0

Behavior4/5

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

Adds real context beyond the annotations: credit consumption, the mandatory confirm flag, the page>11 400 failure mode, and a clarification that a read-like POST does not publish anywhere. This is consistent with readOnlyHint=false and useful, though rate limiting and credential/account behavior are not explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary action and return shape, then constraints and cost in a compact block. Every sentence carries information an agent needs; nothing is padding.

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?

With no output schema, the description helpfully names the return fields, and it covers cost, confirmation, and paging limits for a 6-parameter tool. Minor gaps remain around the account parameter's effect and date_posted usage, but the essentials are present.

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 coverage is 100%, so each parameter is already documented in the schema, including page bounds and the region country code. The description restates region and paging but adds no syntax or default details beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Performs a Google search') and describes the returned payload (url, title, description), which is enough to distinguish it from the platform-specific search siblings like youtube_search or reddit_search. It does not explicitly name which sibling to use instead, so it stops short of a 5.

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 clear operating context: region for localization, page 1-11 only, and the prerequisite confirm=true because the call consumes paid credits. It still offers no explicit when-to-use/when-not guidance relative to the many other search tools in the sibling set.

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

instagram_basic_profileBasic ProfileA

Fetches a lightweight Instagram profile summary by user ID, returning username, full name, biography, profile picture URL, verification status, follower count, following count, media count, and account privacy and type. Ideal for quick lookups or enrichment when you already have the numeric user ID. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`userId`	No	Instagram user id
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior4/5

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

Goes well beyond the annotations by disclosing paid-credit consumption, the confirm=true requirement, and that read-like POSTs do not publish to social platforms. Since readOnlyHint=false could otherwise alarm an agent, the clarification that the POST is read-like is genuinely useful. It stops short of detailing rate limits, failure modes, or what happens when credits are exhausted.

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?

Two front-loaded sentences: the first defines the resource and its payload, the second covers cost and safety. The ten-item field list is long but is the main value-add given there is no output schema, so it earns its space.

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?

With no output schema, enumerating the returned fields is exactly what an agent needs, and cost/confirm behavior is covered. Minor gaps remain around pagination (not applicable here), error behavior, and caching precedence relative to cache_max_age, which is only fully explained in the schema.

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 coverage is 100%, so the schema already documents userId, account, confirm, and cache_max_age including the enum. The description reinforces the numeric-ID meaning of userId and the confirm=true requirement but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (Instagram profile summary by user ID) and enumerates the returned fields, which is unusually concrete. It implicitly distinguishes itself from the sibling instagram_profile by emphasizing 'lightweight' and the numeric-ID prerequisite, but never names the alternative, so sibling differentiation is inferred rather than explicit.

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?

'Ideal for quick lookups or enrichment when you already have the numeric user ID' gives a clear triggering condition and implicitly rules out username-based flows. It also states the credit-consuming nature and the confirm=true gate. No explicit when-not or named alternative tool.

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

instagram_comment_repliesComment RepliesA

Retrieves the public replies to a specific Instagram comment. Pass the post or reel URL and the parent comment's id from the Comments endpoint. Returns reply text, timestamps, engagement counts, parent comment ID, and user details. Paginate with cursor when has_more is true. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The Instagram post or reel URL
`cursor`	No	The cursor to get more replies. Get `cursor` from the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`comment_id`	Yes	The parent comment ID from the Comments endpoint

TDQS

A4.3/5.0

Behavior4/5

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

Adds important behavior beyond the annotations: it may consume paid API credits, requires confirm=true, and clarifies that the read-like POST does not publish to social platforms. This meaningfully offsets the readOnlyHint=false annotation and helps an agent understand the call's side effects.

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?

The description is front-loaded with purpose, then invocation, output, pagination, and credit/confirmation notes. Most sentences earn their place, though the final sentence about read-like POST requests is slightly awkward, keeping it from a perfect score.

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?

With no output schema and open-world annotations, the description does a good job covering return fields, pagination, required confirmation, and credit cost. It omits error handling and auth details, but those are not critical for correct invocation here.

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 description coverage is 100%, so the baseline is 3, but the description still adds value by specifying that `comment_id` comes from the Comments endpoint and that `cursor` is for pagination when `has_more` is true. It does not describe every parameter, but the added context is useful.

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, resource, and scope: retrieves public replies to a specific Instagram comment. This clearly distinguishes it from instagram_comments, which retrieves parent comments, and from other platform comment-reply tools.

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?

Explains how to invoke it by passing the post or reel URL and the parent comment's `id` from the Comments endpoint. This gives clear context for when to use it, though it does not explicitly name an alternative or state when not to use it.

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

instagram_commentsCommentsA

Retrieves comments on a public Instagram post or reel. Each comment includes the comment text, creation timestamp, reply count when Instagram provides it, and commenter details such as username, user ID, verification status, and profile picture URL. child_comment_count can be null when Instagram does not expose the count publicly. Set include_replies=true to fetch the first page of replies for every returned comment. This adds replies, replies_cursor, and has_more_replies to each comment. This option always costs 15 credits because Scrape Creators makes a separate Instagram replies request for every comment in the response. It is possible that no replies are returned, but you will still be charged 15 credits because those reply lookups were performed. This option is much slower than a normal comments request and may time out at 29 seconds. Supports cursor-based pagination to load additional comment pages. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the post or reel to get comments from
`cursor`	No	The cursor to get more comments. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`include_replies`	No	Set to true to include replies for every returned comment. This always costs 15 credits because each comment requires a separate Instagram replies request. You will still be charged 15 credits if no replies are returned. This is much slower and may time out at 29 seconds.

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorld=true) by disclosing the credit-consuming nature, the confirm=true requirement, the fixed 15-credit cost of include_replies even when no replies come back, the slower runtime and 29-second timeout risk, and that child_comment_count can be null. This is exactly the kind of cost/failure-mode disclosure an agent needs.

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-loads purpose and return fields, then the cost/timeout warnings. Some sentences duplicate the schema's include_replies description, but the repetition is on a high-stakes cost point, so it mostly earns its space.

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?

With no output schema, the description still names the returned fields and the optional replies fields, plus pagination and credit/timeout behavior. An agent has everything needed to decide and call correctly.

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 100%, so the schema already documents all five parameters, including the cost warning on include_replies. The description's parameter discussion largely restates the schema rather than adding syntax or format meaning, so the baseline 3 applies.

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 ('Retrieves comments on a public Instagram post or reel') and enumerates the returned fields, so an agent knows exactly what it gets. It is also clearly distinguishable from siblings like instagram_comment_replies or instagram_post_reel_info.

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 clear operational context: cursor pagination for more pages, and the include_replies option with its cost/speed tradeoff, which implicitly routes agents who want replies. It never explicitly names an alternative tool (e.g. instagram_comment_replies) or states when not to use this one, so it falls short of a 5.

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

instagram_embed_htmlEmbed HTMLA

Returns the raw HTML embed snippet for an Instagram user's profile widget. The response contains a single html string that can be inserted into a webpage to render an embeddable Instagram profile card. Requires the user's handle as input. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Instagram handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare a non-read-only, open-world, non-idempotent, non-destructive POST, and the description adds genuinely non-redundant context: it consumes paid API credits, requires confirm=true, and reassures that this read-like POST does not publish to social platforms. The credit cost and confirmation gate are exactly the kind of operational detail annotations cannot express.

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?

Three tight sentences with the purpose front-loaded, followed by the return shape and then the operational caveats. Every sentence carries information; only minor tightening is possible.

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?

With no output schema, the description compensates by describing the return value (a single html string embeddable into a webpage), and it covers the cost/confirmation prerequisites. Complete enough to invoke correctly, though it never states what happens on an invalid handle or whether repeated calls re-bill credits.

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 100%, so all three parameters (handle, account, confirm) are already documented in the schema. The description restates that the handle is required and that confirm=true is needed, but adds no format, syntax, or edge-case detail beyond what the schema provides — the baseline of 3.

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+resource: returns the raw HTML embed snippet for an Instagram user's profile widget, and clarifies the shape of the return (a single html string insertable into a webpage). This is clearly distinguishable from siblings like instagram_profile or instagram_basic_profile, which return profile data rather than an embeddable snippet.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use case (producing an embeddable profile card) and states the handle input requirement, but never explicitly says when to choose this over instagram_profile or any other Instagram sibling, nor does it state any exclusion criteria. Usage must be inferred from the return-value description.

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

instagram_get_reels_by_audio_idGet Reels By Audio IdA

Fetches the reels Instagram exposes for an audio page like instagram.com/reels/audio/{audio_id}/. Pass the audio_id from that URL. Use cursor from the previous response to request the next page when Instagram returns one. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	Pagination cursor returned by Instagram from the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`audio_id`	Yes	The audio id from the Instagram audio page URL.

TDQS

A4.2/5.0

Behavior5/5

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

Adds context the annotations cannot express: paid API credit consumption, the mandatory confirm=true gate, and an explicit clarification that the read-like POST does not publish to social platforms (explaining why readOnlyHint is false). This resolves the most likely point of confusion for an agent reading the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the resource and URL pattern, then pagination, then the credit/confirm constraint. No filler and nothing important is buried.

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?

Covers cost, confirmation, auth framing, and pagination mechanics for a tool with no output schema; the pagination mention implies the response carries a cursor. It stops short of describing the shape of returned reel data, which is a minor gap for an agent consuming 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 100%, so the schema already documents all four parameters including audio_id's URL origin and confirm's requirement. The description reinforces audio_id provenance and cursor pagination but adds no syntax or format detail beyond the schema; baseline 3 applies.

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 (fetches) and resource (reels for an audio page) and pins the exact scope with the source URL pattern `instagram.com/reels/audio/{audio_id}/`. This distinguishes it from sibling tools like instagram_reels or instagram_search_reels, which are not audio-page scoped.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance ('pass the audio_id from that URL', use cursor for the next page), which is genuine how-to-call help. However, it never says when to prefer this over siblings such as instagram_search_reels or instagram_trending_reels, so alternative selection is left implied.

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

instagram_highlights_detailsHighlights DetailsA

Fetches the full contents of a specific Instagram story highlight album by its ID. Returns the highlight's cover image, title, user info, and an items array containing each story with its media type, image or video URLs, dimensions, timestamp, and sticker/interactive element data. Useful for archiving or analyzing individual highlight reels. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	The ID of the highlight to get details for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false and idempotentHint=false already declared, the description adds real context: it explains that the call is a read-like POST that does not publish to social platforms, and that it may consume paid API credits. That reconciles the counterintuitive readOnlyHint and warns about cost, which annotations cannot convey. It stops short of explaining the credit cost or failure behavior.

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 core action, then the return shape, then the credit/confirm warning. The enumerated return fields are dense but informative. Slightly long but nearly every clause carries information an agent needs.

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?

There is no output schema, so the description's enumeration of the returned cover image, title, user info, and items array with media URLs, dimensions, timestamps, and sticker data is doing necessary work. Cost and confirmation semantics are also covered. Pagination and error conditions are the remaining gaps.

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 100%, so all three parameters (id, account, confirm) are already documented in the schema. The description restates the id-based lookup and the confirm requirement but adds no format, default, or edge-case guidance beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetch the full contents of a specific Instagram story highlight album by ID. It clearly differs from list-style siblings, though it never names instagram_story_highlights, so the agent must infer the list-vs-detail split from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a use case ('archiving or analyzing individual highlight reels') and states the confirm=true requirement, which is genuinely actionable. However it never says when to prefer this over instagram_story_highlights, nor what happens if confirm is omitted or false.

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

instagram_popular_searchPopular SearchA

Use this to explore an Instagram topic and the posts Instagram curates for it. It scrapes the public /popular/{query} page without requiring an Instagram login. The first page returns the topic title, numeric total media count, Instagram's generated description and sources, suggested terms, posts, and an opaque cursor. Pass that cursor with the same query to fetch more posts. Later pages return query, posts, cursor, and has_more only. For an exact hashtag through Google-indexed results, use /v1/instagram/search/hashtag. For reels only, use /v2/instagram/reels/search. Each successful request costs 1 credit. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The Popular topic to search for.
`cursor`	No	The opaque cursor returned by the previous response. Use it with the same query to fetch the next page of posts.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the pagination contract (first page returns title, media count, description, sources, suggested terms, posts, cursor; later pages return only query, posts, cursor, has_more), the cost ('Each successful request costs 1 credit'), the confirm=true requirement, and the login-free nature. It also reconciles the readOnlyHint=false annotation by clarifying 'Read-like POST requests do not publish to social platforms.'

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 purpose, then pagination, then alternatives, then cost. Every sentence carries information, though the cursor mechanics are partly restated from the schema, producing mild redundancy for a dense description.

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?

With no output schema, the description compensates by enumerating the fields returned on first vs. later pages, plus cost, auth, and confirm semantics. An agent has everything needed to call it, page through results, and anticipate shape changes.

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 adds real value: it explains the cursor's lifecycle and that it must be paired with the same query, and that later pages have a reduced return shape. It adds little on 'account' and 'confirm' beyond the schema, keeping it short of a 5.

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 (explore/scrape) and resource (Instagram curated /popular/{query} topic page) with explicit scope: public page, no login. It distinguishes itself from near-siblings by naming the hashtag-search and reels-search alternatives, so an agent can select it without opening other 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?

Explicitly routes the agent: 'For an exact hashtag through Google-indexed results, use /v1/instagram/search/hashtag. For reels only, use /v2/instagram/reels/search.' It also states the pagination workflow (pass cursor with same query) and the credit/confirm precondition, covering when and when-not to call it.

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

instagram_post_reel_infoPost/Reel InfoA

Fetches detailed metadata for a single Instagram post or reel by shortcode or URL. Returns caption text, like count, comment count, video URL, video play count, video duration, display images, owner info, tagged users, carousel sidecar children when applicable, and the published time in data.xdt_shortcode_media.created_at as an ISO 8601 UTC date. The original Unix timestamp remains available in data.xdt_shortcode_media.taken_at_timestamp. Play counts are Instagram-only views and exclude cross-posted Facebook views. Set include_play_count=false to omit the play count and skip its additional fetch for a faster response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Instagram post or reel URL
`trim`	No	Set to true to get a trimmed response
`region`	No	2 letter country code to set the proxy in
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)
`download_media`	No	Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
`include_play_count`	No	Set to false to omit `video_play_count` and skip its additional fetch for a faster response. Defaults to true.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations give readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds real value beyond that: paid-credit consumption, mandatory confirm=true, the clarification that the read-like POST does not publish to social platforms, and play-count semantics (Instagram-only, excludes cross-posted Facebook views). It stops short of explaining retry/caching cost trade-offs in depth.

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?

Purpose is front-loaded in the first sentence, followed by return fields and cost/param notes. It is a single dense block, but each sentence carries useful information for a tool with no output schema, so little is wasted.

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?

With no output schema, the description ably covers the return shape (caption, like/comment counts, video URL, play count, duration, images, owner, tagged users, carousel children, timestamps) plus currency semantics and the credit/confirm model. An agent has what it needs to call and interpret it.

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 description coverage is 100%, so the baseline is 3 and the schema already documents url, trim, region, account, confirm, cache_max_age, download_media, and include_play_count. The description nonetheless adds meaning around include_play_count (skips an additional fetch for speed) and the play-count exclusion rule, which is genuine added semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (detailed metadata for a single Instagram post or reel) with the identifier type (shortcode or URL). The 'single' qualifier implicitly separates it from list tools like instagram_posts and instagram_reels, though no sibling is named explicitly to sharpen that boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear (retrieve metadata for one post/reel), and it notes the confirm=true prerequisite and paid-credit caveat. However, it never states when to choose this over instagram_posts, instagram_reels, or instagram_transcript, nor any when-not condition. Prerequisites are present but alternative-routing guidance is absent.

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

instagram_postsPostsA

Returns a paginated feed of a user's public Instagram posts, including reels, photos, videos, and carousels. Each item includes media type, shortcode, caption text, like count, comment count, play count, video URLs, image URLs, tagged users, and the published time in items[].created_at as an ISO 8601 UTC date. The original Unix timestamp remains available in items[].taken_at. Play counts reflect Instagram-only views and exclude cross-posted Facebook views. Supports cursor-based pagination via next_max_id for scrolling through the full timeline. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`handle`	Yes	Instagram handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`next_max_id`	No	Cursor to get next page of results.

TDQS

A3.7/5.0

Behavior4/5

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

The annotations declare readOnlyHint=false, which could mislead an agent into thinking this mutates data; the description resolves that ambiguity by clarifying these are 'read-like POST requests' that 'do not publish to social platforms' and that confirm=true is required. It also discloses credit consumption and the play-count caveat (Instagram-only views, excludes Facebook). It stops short of covering rate limits or auth.

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?

The response shape and scope are front-loaded, followed by pagination and then the credit/confirm caveat — a sensible ordering. It is dense with enumerated fields, but each clause carries signal rather than filler.

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?

There is no output schema, so the description appropriately enumerates return fields (media type, shortcode, caption, counts, URLs, tagged users, created_at/taken_at). Pagination, credit cost, and confirm are all covered, leaving little an agent needs to know unaddressed.

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 100%, so the baseline is 3 and the schema already documents handle, account, trim, confirm, and next_max_id. The description adds only marginal value by explaining that next_max_id enables cursor scrolling through the full timeline, and says nothing about account or trim beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource ('Returns a paginated feed of a user's public Instagram posts') and enumerates the media types covered (reels, photos, videos, carousels), so the agent knows exactly what it fetches. It does not, however, explicitly differentiate itself from siblings like instagram_reels or instagram_user_tagged_posts, which overlap in scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies an operational prerequisite ('requires confirm=true') and warns that credits may be consumed, which is real usage friction the agent must handle. But it never states when to choose this tool over instagram_reels, instagram_user_tagged_posts, or instagram_profile, so alternative selection is left to inference.

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

instagram_profileProfileA

Retrieves comprehensive public Instagram profile information including biography, bio links, follower and following counts, verification status, and profile picture URLs. Also returns recent timeline posts with engagement metrics such as likes, comments, and video view counts, plus a list of related profiles. Useful for account overview, audience analysis, or discovering similar creators. Instagram may return media_count as null or return only the current post batch in edge_owner_to_timeline_media.count. Use Profile Post Count when you specifically need the total number of posts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`handle`	Yes	Instagram handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior4/5

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

Despite annotations declaring readOnlyHint=false and destructiveHint=false, the description adds crucial context: 'Potentially consumes paid API credits; requires confirm=true' and clarifies that 'Read-like POST requests do not publish to social platforms.' It also warns about a known data quirk (media_count may be null). It does not mention rate limits or caching behavior beyond the schema's own cache_max_age explanation, but the credit-consumption warning is substantive.

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-loads the return payload, then caveats, then usage. Every sentence carries information (field list, use cases, data quirks, credit warning). Slightly dense with the multi-clause caveat sentence, but no redundancy.

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?

No output schema, so the description compensates by enumerating returned fields (bio, counts, posts, engagement, related profiles) and warns about a known data-quality issue (media_count null / batch-only). It covers the read-like-POST publishing caveat and credit cost. Missing: explicit mention of what cache_max_age does, though the schema covers it.

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 100%, so the schema already documents all five parameters (trim, handle, account, confirm, cache_max_age). The description reinforces 'requires confirm=true' and the credit cost, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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?

Specific verb+resource: 'Retrieves comprehensive public Instagram profile information' with a detailed enumeration of returned fields (biography, bio links, counts, verification, picture URLs, recent posts, related profiles). Distinguishes from sibling instagram_basic_profile and instagram_posts by naming the fuller scope, and explicitly routes to instagram_profile_post_count for post totals.

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 use-case contexts ('account overview, audience analysis, or discovering similar creators') and explicitly routes to 'Profile Post Count' when total post count is needed. Does not, however, contrast against the very similar sibling instagram_basic_profile or instagram_posts, leaving the agent to infer which profile endpoint to select.

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

instagram_profile_post_countProfile Post CountA

Returns the post count shown on a public Instagram profile. Use this endpoint when Profile returns media_count as null or edge_owner_to_timeline_media.count contains only the current batch size. This endpoint makes a separate Instagram profile-page request so it does not add latency to the main Profile endpoint. Full values such as 12,345 Posts return the exact integer with is_estimated set to false. For profiles with more than 10,000 posts, Instagram may expose only a compact value such as 12K Posts or 1.2M Posts. Set allow_estimated=true to return the scaled integer with is_estimated set to true. Estimated counts are opt-in: when allow_estimated is omitted or false, the endpoint returns an uncharged 422 response explaining that exact precision is unavailable. If Instagram omits the count entirely, the endpoint returns an error without deducting a credit. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Instagram handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`allow_estimated`	No	Set to true to return scaled estimates when Instagram abbreviates counts for profiles with more than 10,000 posts. Defaults to false; false or omitted returns an uncharged 422 when only an estimate is available.

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true) by disclosing that the call consumes paid credits, requires confirm=true, that it is a read-like POST that does not publish to social platforms, the uncharged 422 when precision is unavailable, and no credit deduction on error. These are exactly the operational traits an agent needs before invoking a credit-consuming endpoint.

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?

Purpose and the primary when-to-use condition are front-loaded, and every sentence carries operational information (estimation, is_estimated flag, 422 behavior, credit semantics). It is somewhat dense and could compress the final credit/confirmation paragraph, but there is no filler.

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?

With no output schema, the description correctly carries the return contract itself: an exact integer with is_estimated=false for full values, or a scaled integer with is_estimated=true for abbreviated counts. Combined with the error/credit behavior, an agent has everything needed to call and interpret the result.

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 adds workflow-level meaning: it explains the concrete consequence of allow_estimated being false/omitted (an uncharged 422) and ties confirm=true to credit consumption, which the schema describes only tersely.

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?

The description opens with a specific verb+resource: 'Returns the post count shown on a public Instagram profile.' It further distinguishes itself from the sibling instagram_profile by naming the exact failure mode (media_count null, or edge_owner_to_timeline_media.count equal to batch size) that this tool exists to resolve.

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?

It states precisely when to use this tool ('when Profile returns media_count as null or edge_owner_to_timeline_media.count contains only the current batch size') and the condition that selects the alternative behavior ('Set allow_estimated=true ... when only an estimate is available'). Fallback routing is explicit rather than inferred.

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

instagram_reelsReelsA

Returns a paginated list of a user's public Instagram reels (short-form videos). Each reel includes its shortcode, play count, like count, comment count, video versions with download URLs, thumbnail image, owner info, and the published time in items[].media.created_at as an ISO 8601 UTC date. With trim=true, use items[].created_at. The original Unix timestamp remains available as taken_at. Note that reel captions are not returned by this endpoint. Play counts are Instagram-only views and exclude cross-posted Facebook views. Supports cursor-based pagination via max_id; providing a user_id instead of a handle yields faster responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	No	Instagram handle. Use user_id for faster response times.
`max_id`	No	Max id to get more reels. Get 'max_id' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	Instagram user id. Use this for faster response times.

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations, it discloses that the call consumes paid credits and requires confirm=true, clarifies why a read-like POST does not publish to social platforms, notes that captions are not returned, and explains that play counts exclude Facebook cross-posts. This is rich behavioral context the structured fields don't carry.

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?

The description is dense and slightly long, but it is front-loaded with the resource definition and then layers the high-value caveats (timestamps, missing captions, credit cost). Nearly every sentence carries operationally useful information, with only minor compression possible.

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?

With no output schema, the description carries the burden of explaining returns, and it does so thoroughly (fields, timestamp semantics, missing captions, view-count caveats). Combined with the annotations and a fully documented schema, an agent has what it needs to call this correctly.

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 adds real meaning: trim shifts the timestamp field to items[].created_at, max_id drives cursor pagination, user_id yields faster responses, and confirm gates the credit-consuming call. The remaining fields (account) get no prose, but the added value is genuine.

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?

The description names a specific verb and resource ("Returns a paginated list of a user's public Instagram reels") and scopes it to short-form videos. It also enumerates the returned fields, so an agent can distinguish this per-user listing from search-based siblings like instagram_search_reels without opening a schema.

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?

It gives concrete operating conditions: cursor pagination via max_id, a preference for user_id over handle for speed, and the confirm=true credit prerequisite. It does not explicitly route the agent to or away from sibling reels endpoints, so usage is clear but lacks explicit alternatives.

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

instagram_search_hashtag_postsSearch Hashtag PostsA

Use this when you know the exact hashtag and want Google-indexed public Instagram posts or reels, optional date filters, and pagination. It returns post details such as caption, engagement, owner, and post time. Results are best-effort and not a complete Instagram-native hashtag feed. For an Instagram-curated topic page with generated context and suggested terms, use /v1/instagram/search/popular. Pass media_type=reels to only return reels. Cursors are limited to pages 1 through 11; cursor 12 or greater returns a 400 response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	The cursor returned by the previous response. It is the next Google results page number and cannot exceed 11; cursor 12 or greater returns a 400 response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`hashtag`	Yes	The hashtag to search for. Include or omit the #.
`media_type`	No	Use all to search public posts and reels, or reels to only return reels. Defaults to all.
`date_posted`	No	Only return Google-indexed posts found in this relative window.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations mark readOnlyHint=false, but the description justifies and clarifies this: it is a read-like POST that does not publish, yet consumes paid API credits and requires confirm=true. It also discloses the best-effort/incomplete nature of results and the hard cursor ceiling (page 11, 400 at cursor 12), which annotations cannot express.

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 when-to-use clause and alternative routing, and every sentence carries information. It is slightly dense/long with credit and error constraints stacked at the end, but nothing is wasted.

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?

No output schema exists, and the description compensates by naming the returned fields (caption, engagement, owner, post time). Combined with the result-quality caveat, pagination limits, and confirm requirement, an agent has everything needed to call it correctly.

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 100%, so cursor limits, media_type enum, date_posted windows, and the confirm requirement are already documented in the schema; the description largely restates them rather than adding new syntax or format meaning. The one useful framing is tying confirm=true to the credit-consuming research flow.

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 ('search ... public Instagram posts or reels') scoped to known hashtags, and explicitly distinguishes itself from the curated topic-page sibling (/v1/instagram/search/popular). An agent can route to it without opening the schema.

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 a clear when-to-use condition ('when you know the exact hashtag'), names the alternative for the other case (Instagram-curated topic page), and adds the confirm=true prerequisite for the credit-consuming call.

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

instagram_search_instagramSearch InstagramA

Use this for Instagram-native account, hashtag, or place lookup. It returns ranked users, hashtags, places, and keyword suggestions from Instagram itself. It is not Google-indexed, does not require an Instagram login, returns one page only, and does not return posts. For an Instagram-curated topic page with posts, use /v1/instagram/search/popular. For the same native account results in a profile-only response, use /v1/instagram/search/profiles. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The username, hashtag, place, or keyword to search for.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the annotations: not Google-indexed, no Instagram login required, one page only (no pagination), no posts returned, consumes paid credits, confirm=true required, and it reconciles the odd readOnlyHint=false annotation by clarifying that read-like POSTs do not publish to social platforms.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool is, then exclusions, then alternatives, then the operational warning. Every clause carries non-redundant information; nothing is padding.

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?

With no output schema, the description compensates by naming the return shape (ranked users, hashtags, places, keyword suggestions) and the single-page limitation. Billing and auth prerequisites are covered, so an agent has everything needed to call it correctly.

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 100%, so query, account, and confirm are already documented in the schema; that sets the baseline at 3. The description reinforces confirm (credit-consuming, must be true) but adds no new syntax, format, or constraint meaning beyond the schema text.

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 ('Instagram-native account, hashtag, or place lookup') and precisely enumerates the returned entity types (ranked users, hashtags, places, keyword suggestions). It explicitly separates itself from two named siblings, so an agent can route without opening any schema.

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 explicit when-to-use and when-not-to-use conditions plus the exact alternatives: '/v1/instagram/search/popular' for curated topic pages with posts, '/v1/instagram/search/profiles' for profile-only native account results. No inference is required from the agent.

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

instagram_search_instagram_profilesSearch Instagram ProfilesA

Use this for Instagram-native profile lookup. It returns every account in Instagram's first ranked native result set, then performs bounded best-effort enrichment for the first 10 accounts to preserve the previous profile fields such as biography, bio links, account flags, and follower/following/media counts. Results after the first 10 retain native ID, username, full name, verification status, profile photo, and URL, while unavailable detail fields are null or empty. It does not search Google-indexed bios or captions, Google title/description fields are null, and pagination is not supported. For users, hashtags, places, and keyword suggestions together, use /v1/instagram/search. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The profile name or username to search for.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing credit consumption, the confirm=true gate, and that read-like POSTs do not publish to social platforms. It also details the enrichment behavior: only the first 10 accounts get full fields, later results keep a reduced field set, and unavailable details are null or empty.

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?

Purpose and scope are front-loaded, and every sentence carries operational information (enrichment cutoff, null behavior, no pagination, cost/confirm). The single dense paragraph is long but not padded; light restructuring could improve scanability without losing content.

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?

With no output schema, the description compensates by enumerating returned fields and the enrichment cutoff, describing null/empty degradation, and covering cost, confirmation, and publication safety. Nothing an agent needs to invoke or interpret this call is missing.

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 100%, so query, account, and confirm are already documented at the schema level; baseline 3 applies. The description reinforces the confirm requirement and its credit-cost rationale, but adds no syntax or format detail for query or account beyond 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?

Opens with a specific verb and resource ('Instagram-native profile lookup') and immediately bounds scope by contrasting with what it does not cover ('does not search Google-indexed bios or captions'). It routes the agent to the general search route for cross-entity queries, so it is separable from instagram_search_instagram and instagram_profile without opening a schema.

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?

States the selecting condition ('Instagram-native profile lookup'), names an alternative for the broader case (users, hashtags, places, keyword suggestions together -> /v1/instagram/search), and explicitly lists exclusions (Google-indexed bios/captions, Google title/description fields, no pagination). The when/when-not/alternative triad is all present.

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

instagram_search_reelsSearch ReelsA

Use this when you only want Google-indexed Instagram reels matching a keyword or phrase, with optional date filters and pagination. It returns reel media, engagement, owner, location, and audio details. Results are best-effort rather than a complete Instagram-native search. For Instagram-curated topic posts, use /v1/instagram/search/popular. For an exact hashtag across posts and reels, use /v1/instagram/search/hashtag. Pages 1 through 11 are supported; page 12 or greater returns a 400 response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to return. Must be between 1 and 11; page 12 or greater returns a 400 response.
`query`	Yes	The keyword to search for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`date_posted`	No	Google-indexed date window. Recent hour/day filters are not supported because Google does not index Instagram reels reliably enough in those windows.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations declare openWorldHint=true and idempotentHint=false but leave the paid-credit and confirm requirement unstated; the description supplies both, plus the 400 response behavior on page>=12 and the 'best-effort rather than complete Instagram-native search' coverage caveat. It does not describe return shape beyond listing field families, and does not clarify why a read-like POST is non-readOnly in the annotation, so it is short of full disclosure.

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 core 'when to use' statement, then alternatives, then limits, then cost/auth. Efficient across six sentences, but the closing 'Read-like POST requests do not publish to social platforms' is somewhat tangential and the field enumeration ('reel media, engagement, owner, location, audio') is more inventory than decision-relevant.

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?

Absent an output schema, the description names the returned field families; it covers cost/auth (confirm=true, paid credits), pagination bounds with failure mode, scope caveat (best-effort), and sibling routing. That is everything needed to invoke correctly.

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 100%, so the schema already documents page bounds, the account-vs-remote-ID distinction, confirm=true, and the enum values. The description adds the date_posted rationale (hour/day unsupported due to Google indexing) and the page-11 ceiling, but mostly restates what the schema already carries. Baseline 3 for full coverage is correct.

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 (search) and resource (Google-indexed Instagram reels) and explicitly scopes it against sibling alternatives by naming /v1/instagram/search/popular and /v1/instagram/search/hashtag with their distinct behaviors. An agent can differentiate this from instagram_popular_search and instagram_search_hashtag_posts 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?

Explicit 'use this when' framing plus two named alternatives with the selecting condition for each ('curated topic posts' -> popular, 'exact hashtag across posts and reels' -> hashtag). Also states the hard page-12 failure boundary, which is a routing-relevant constraint.

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

instagram_story_highlightsStory HighlightsA

Lists all story highlight albums for an Instagram user. Each highlight includes its ID, title, cover thumbnail URL, and owner info with username and profile picture. Accepts either a user_id or handle; providing user_id yields faster responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	Instagram handle. Use user_id for faster response times.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	Instagram user id. Use for faster response times.

TDQS

A4.1/5.0

Behavior5/5

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

The annotations declare readOnlyHint=false and idempotentHint=false, which would otherwise look like a mutation; the description resolves this by explaining that this is a read-like POST that does not publish to social platforms. It also discloses that the call consumes paid API credits and requires confirm=true, and lists the returned fields despite no output schema existing.

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?

Four sentences, front-loaded with the core listing behavior, then returns, then parameter guidance, then the credit/confirm caveat. Dense but each sentence carries distinct information; only the parameter/speed sentence mildly overlaps the schema text.

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?

With no output schema, the description usefully enumerates return fields, and it covers the credit and confirm prerequisites tied to the false readOnlyHint. Gaps remain: no routing to instagram_highlights_details, no mention of pagination or behavior when confirm is omitted.

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 100%, so the baseline is 3. The description restates the user_id/handle speed tradeoff and confirm=true requirement that the schema already documents, adding little new parameter-level meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: 'Lists all story highlight albums for an Instagram user,' and even enumerates the returned fields (ID, title, cover thumbnail, owner info). It implies a distinction from the sibling instagram_highlights_details (list-all vs. one-detail) but never names it, so the differentiation is left implicit rather than explicit.

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?

It supplies real call-time guidance: pass either user_id or handle, prefer user_id for speed, and set confirm=true for the credit-consuming call. What is missing is routing guidance against the close sibling instagram_highlights_details and any note on when not to use this tool.

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

instagram_transcriptTranscriptA

Generates an AI-powered speech-to-text transcription for an Instagram video post or reel. The video must be under 2 minutes long. Returns a transcripts array with each item's shortcode and transcribed text; carousel posts produce one transcript per video slide. Expect 10-30 second response times, and null when no speech is detected. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Instagram post or reel URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4/5.0

Behavior4/5

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

Adds behavioral details beyond what annotations provide: 'under 2 minutes' limit, 10-30 second response times, null on no speech, and credit consumption requiring confirm=true. However, annotations already declare readOnlyHint=false and destructiveHint=false; the description notes 'Read-like POST requests do not publish to social platforms,' which clarifies the otherwise confusing write-esque annotation.

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-loads the core purpose first, then adds necessary operational caveats. The sentence about carousel posts and the final sentence about read-like POST requests are slightly extraneous but not harmful.

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?

Complete for a transcript tool with 100% schema coverage and no output schema. The description covers duration limits, response time, null behavior, carousel handling, credit cost, and the confirm requirement, giving an agent everything needed to call it correctly.

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 100%, so the schema already documents all parameters. The description adds only 'requires confirm=true' and the URL input implication, but nothing beyond the schema's own explanation.

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 (Generates transcription) and resource (Instagram video post or reel), clearly distinguishing it from related siblings like tiktok_transcript or youtube_transcript.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage context via 'Instagram video post or reel' and 'under 2 minutes', but does not explicitly state when to use this vs. e.g. instagram_post_reel_info or when not to use (e.g., for static image posts).

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

instagram_trending_reelsTrending ReelsA

Fetches trending reels from Instagram's public instagram.com/reels page. Instagram only gives a small batch at a time and the results can overlap, so call this endpoint over and over when you want more. Each call should return new-ish results, but expect some duplicates because that is how Instagram's reels page behaves too. Returns reels, an array of reel objects with shortcode, URL, caption, media URLs, engagement counts when Instagram exposes them, and user info. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior5/5

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

Adds substantial context beyond annotations: explains that the endpoint consumes paid API credits, requires confirm=true, returns overlapping results, and that read-like POST requests do not publish to social platforms. These details clarify the safety and cost profile in ways the structured annotations do not, and they do not contradict the declared hints.

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?

The description is front-loaded and mostly efficient, covering key points in a logical order. However, the warning about duplicates is repeated across two sentences, adding slight redundancy that a tighter edit could remove without losing meaning.

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 a tool with no output schema, the description adequately describes the return structure (`reels` array with shortcode, URL, caption, media URLs, engagement counts, and user info). It also covers credit consumption, confirm requirement, and duplicate behavior, leaving no critical gap for correct invocation.

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 100%, so both parameters are already documented in the input schema. The description reinforces the confirm=true requirement but does not add new meaning to the account parameter or clarify any other semantic nuance beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetches trending reels from Instagram's public instagram.com/reels page. This distinguishes it from profile-based tools like instagram_reels, but it does not explicitly name an alternative sibling or contrast the scope with instagram_search_reels. The purpose is clear without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage instructions for pagination: call repeatedly to get more, and expect duplicates. However, it does not state when to prefer this tool over siblings like instagram_reels or instagram_search_reels, nor does it specify exclusions or prerequisites beyond the confirm requirement.

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

instagram_user_tagged_postsUser Tagged PostsA

Returns up to 10 public posts per page from an Instagram user's Tagged tab. Each item is a flat post object with its shortcode, caption, media type, engagement counts, media URLs, and owner details. Keep passing the returned cursor to fetch additional pages until has_more is false. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	Cursor returned by the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	Yes	Numeric Instagram user ID.

TDQS

A4/5.0

Behavior5/5

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

Despite annotations declaring readOnlyHint=false and non-idempotent, the description explains why: 'Potentially consumes paid API credits; requires confirm=true' and 'Read-like POST requests do not publish to social platforms.' This resolves the security-relevant tension between a read operation and a non-readOnly POST, and adds cost/pagination behavior the annotations cannot convey.

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?

Four sentences, front-loaded with the core action and scope, then return shape, pagination, and the credit/confirm caveat. Every sentence carries information; only the return-field enumeration is slightly dense, but it substitutes for a missing output schema.

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?

With no output schema, the description compensates by enumerating the returned fields (shortcode, caption, media type, engagement counts, media URLs, owner details) and explaining pagination termination via has_more. Combined with the annotations and full schema coverage, an agent has everything needed to call it correctly.

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 coverage is 100%, so all four parameters are already documented in the schema (cursor, account, confirm, user_id). The description reinforces confirm and cursor semantics through the pagination and credit sentences, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns up to 10 public posts per page from an Instagram user's Tagged tab,' which distinguishes it from the sibling instagram_posts by scoping to the Tagged tab. The scope is explicit enough for an agent to pick it over instagram_posts, though it does not name that sibling directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via pagination guidance ('Keep passing the returned cursor... until has_more is false') and the confirm/credit requirement, but never states when to choose this over instagram_posts, instagram_reels, or instagram_search_hashtag_posts. Guidance is present but indirect, matching a 3.

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

kick_clipClipA

Fetches detailed data for a Kick clip by URL, including video, metadata, and channel info. Returns clip id, title, clip_url, thumbnail_url, video_url, view_count, likes_count, duration, privacy status, and is_mature flag. Also includes category details (name, slug), creator info (username), and channel info (username, profile_picture). Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Kick clip URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Beyond the annotations, it discloses that the operation consumes paid credits, that confirm must be true, and that the read-like POST does not publish to social platforms, explaining the otherwise-confusing readOnlyHint=false. It does not describe rate limits or pagination, but the cost and confirmation context is genuinely additive.

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 enumerates return fields and operational caveats. The field list is dense but earns its place given there is no output schema; overall appropriately sized.

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?

With no output schema, the enumerated return fields (clip id, video_url, view_count, privacy status, category/creator/channel info) usefully describe the response, and the credit/confirm caveats cover operational needs. Adequate for a single-URL fetch tool.

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 100%, so the baseline is 3. The description confirms confirm=true semantics and account credential selection but adds no syntax or format detail beyond what the schema already documents.

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 (fetches detailed data for a Kick clip by URL) and enumerates the returned fields, clearly distinguishing it from sibling tools like kick_clip_transcript. An agent can identify exactly what it does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It discloses that the call consumes paid API credits and requires confirm=true, which is real usage guidance, but it never says when to prefer this over the sibling kick_clip_transcript or other clip tools. Usage is implied rather than compared against alternatives.

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

kick_clip_transcriptClip TranscriptA

Gets a transcript from a public Kick clip. The endpoint checks Kick's native captions first. Set use_ai_as_fallback to true to use AI transcription only when native captions are unavailable. Native transcripts cost 1 credit, AI transcripts cost 10 credits, and no credits are charged when no transcript is found. transcript_source is native, ai, or null. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Kick clip URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`use_ai_as_fallback`	No	Use AI transcription only when native captions are unavailable. Costs 10 credits when an AI transcript is returned. Defaults to false.

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations (which only say readOnly=false, destructive=false) by disclosing credit costs per path, the zero-charge case, the required confirm=true, and the reassuring note that read-like POSTs do not publish to social platforms. This is exactly the paid-API context an agent needs.

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 purpose, then the fallback rule, then cost/auth. Mostly efficient, though the cost figures are restated between the description and the schema, and the final sentence about publishing is a slight tangential add.

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?

With no output schema, the description helpfully enumerates transcript_source values and credit outcomes, and covers auth (confirm) and cost. It doesn't describe the full transcript payload shape, but for a read-like transcript fetch that is a minor gap.

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 3-baseline applies, but the description adds real value by tying use_ai_as_fallback to its cost consequence (10 credits) and the native-vs-AI fallback behavior, plus explaining transcript_source's possible values. It adds meaning beyond the schema without needing to duplicate URL/account semantics.

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 ('Gets a transcript from a public Kick clip') and implicitly distinguishes itself from the sibling kick_clip (clip metadata) by naming the transcript output. An agent can tell what it retrieves without opening the schema.

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?

Explains the conditional path clearly: native captions are checked first, and use_ai_as_fallback=true only triggers AI when native is unavailable. It also states credit costs and the confirm=true prerequisite. It stops short of naming sibling alternatives (e.g., twitch_clip_transcript / kick_clip) for cross-platform selection, so a 4 rather than 5.

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

komi_komi_pageKomi pageA

Scrapes a Komi page by URL, extracting the creator's profile, social links, and featured content. Returns id, username, avatar, displayName, bio, and social accounts (instagram, tiktok, youtube, twitter, facebook, snapchat). Also includes links, an array of link and product objects each with id, url, title, type, thumbnail, and optional price and currency for products. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to Komi page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, which would otherwise look alarming for a scrape; the description proactively explains that these are read-like POST requests and that they do not publish to social platforms. It also discloses credit consumption and confirmation requirements. It stops short of describing rate limits or caching fallback behavior beyond what the schema already says.

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?

The action is front-loaded in the first clause, and the return-field enumeration earns its space because there is no output schema. It is somewhat dense but no sentence is wasted.

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?

With no output schema, the description compensates by listing the returned fields, and it covers the credit/confirm and read-vs-publish behavioral concerns. An agent has enough to invoke it correctly; only sibling routing guidance is missing.

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 100%, so the schema already documents url, account, confirm, and cache_max_age thoroughly, including the enum semantics. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Scrapes a Komi page by URL') and enumerates exactly what is extracted (profile, social links, featured content) plus the returned fields. It doesn't explicitly contrast with near siblings like linktree_linktree_page or pillar_pillar_page, which is the only thing keeping it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Conveys the key operational condition (requires confirm=true, consumes paid credits, cache_max_age avoids credit spend), which is genuine usage guidance. However, it never says when to choose this tool over the similar bio-link scrapers in the sibling list, so routing is left to inference.

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

kwai_postPostA

Fetches public Kwai post details including caption, media URLs, cover images, counts, author info, and music metadata. Uses Kwai's public web API endpoint, not HTML scraping. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Kwai post URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, which could mislead an agent into thinking this mutates state. The description resolves that tension by clarifying it is a read-like POST that does not publish to social platforms, and adds the credit-consumption and confirm=true requirements. Return format is unspecified, but the payload fields are listed.

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?

Three sentences, front-loaded with the capability and followed by the transport detail and the cost/safety caveat. No filler, though the middle sentence about the API endpoint is the least essential.

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?

With no output schema, the description usefully enumerates the returned fields, and it discloses the credit/confirm preconditions. It stops short of describing pagination or error behavior for a URL-based fetch, but covers the essentials for correct invocation.

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 100%, so the schema already documents url, account, and confirm. The description reinforces that confirm is required for the credit-consuming call but adds little beyond the schema's own wording. Baseline 3 is appropriate.

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 ("Fetches public Kwai post details") and enumerates the returned payload (caption, media URLs, cover images, counts, author info, music metadata), which clearly separates it from kwai_profile and kwai_user_posts siblings. An agent knows exactly what this tool retrieves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives operational guidance — consumes paid credits, requires confirm=true — but never states when to choose this over kwai_profile or kwai_user_posts, nor that a Kwai post URL is the expected input needed for this path versus a profile lookup. Usage is implied rather than routed.

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

kwai_profileProfileA

Fetches public Kwai profile data including username, bio, avatar, verification status, gender, and public counts. Uses Kwai's public web API endpoint, not HTML scraping. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Kwai profile URL. Use this or handle.
`handle`	No	Kwai profile handle. Use this or url.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing that calls may consume paid API credits, that confirm=true is required, that it hits Kwai's public web API rather than scraping HTML, and that the read-like POST does not publish to social platforms. That last point usefully resolves the tension with readOnlyHint=false and destructiveHint=false.

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?

Three sentences, front-loaded with purpose, then implementation, then the operational constraints (credits, confirm, no publishing). Tight, though the 'not HTML scraping' clause is minor color rather than essential information.

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?

No output schema exists, so the description appropriately enumerates returned fields and adds the credit/confirm constraints an agent needs before calling. It leaves return shape details and error/rate-limit behavior unstated, but the core picture is complete for a profile-read tool.

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 100%, so the schema already documents url, handle, account, and confirm with clear semantics. The description adds no additional parameter meaning beyond what the structured fields provide, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetches') and resource ('public Kwai profile data') and enumerates the returned fields (username, bio, avatar, verification, gender, counts), which clearly separates it from kwai_user_posts and kwai_post. It does not, however, explicitly name a sibling or scope boundary, so differentiation rests on the name plus field list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: supply url or handle to retrieve a profile. There is no explicit when-to-use, no exclusions, and no routing to alternatives such as kwai_user_posts or kwai_post among ~130 siblings, so the agent must infer the choice.

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

kwai_user_postsUser PostsA

Fetches a paginated list of public Kwai posts for a user, including captions, media URLs, covers, counts, author info, and the next cursor when more results are available. Uses Kwai's public web API endpoint, not HTML scraping. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Kwai profile URL. Use this or handle.
`count`	No	Number of posts to return, max 50
`cursor`	No	Cursor from the previous response for the next page
`handle`	No	Kwai profile handle. Use this or url.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.2/5.0

Behavior4/5

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

Goes beyond annotations by disclosing credit consumption, the confirm=true gate, that the read-like POST does not publish anything, and that it hits the public web API rather than scraping. These are exactly the traits (cost, auth/confirmation, side-effect safety) an agent needs and that the hints alone don't convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, the core fetch behavior front-loaded ahead of the cost/confirmation constraints. No filler.

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?

With no output schema, the description compensates by naming the returned fields and the next-cursor pagination model, and it flags the credit/confirm requirements. Slightly short of complete because it omits any guidance on required vs optional inputs (e.g. url or handle).

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 100%, so the schema already documents url/handle/count/cursor/account/confirm. The description only reinforces confirm=true and cursor-based paging, so baseline 3 is appropriate.

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?

Specific verb (fetches) plus resource (paginated list of public Kwai posts for a user), with the returned fields enumerated. An agent can distinguish it from kwai_profile and kwai_post from the text alone.

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 clear operational context: uses the public web API rather than HTML scraping, requires confirm=true, and consumes paid credits. It does not, however, explicitly say when to prefer this over the sibling kwai_profile or kwai_post, so routing still needs inference.

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

linkbio_linkbio_pageLinkbio pageA

Scrapes a Linkbio (lnk.bio) page by URL, extracting the creator's profile and all their links. Returns handle, id, social accounts (instagram, tiktok, youtube, twitter, whatsapp), email, website, and links — an array of link objects each with url and text. Contact fields come from the submitted public Linkbio page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to Linkbio (lnk.bio) page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior4/5

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

Adds real context beyond annotations: credit consumption, the confirm=true gate, caching semantics, and the clarifying note that 'read-like POST requests do not publish to social platforms' — which usefully explains the readOnlyHint=false flag. Omits whether credentials/account scoping is required or the failure modes, so not a full 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?

Front-loads the core purpose and return shape, then covers credits and the removal contact. Mostly tight, though the removal-request sentence is tangential to invocation and slightly dilutes focus.

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?

No output schema exists, so the description carries return-value burden — and it does describe the returned fields (handle, id, socials, email, website, links). Combined with credit/cache behavior, an agent has enough to invoke it correctly, though account-scoping and error behavior are unaddressed.

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 100%, with each of the four parameters (url, account, confirm, cache_max_age) already documented and the enum enumerated. The description adds no per-parameter meaning beyond what the schema provides, so the baseline 3 applies.

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 ('Scrapes a Linkbio (lnk.bio) page by URL') and enumerates exactly what it extracts, so an agent can distinguish it from the many sibling page scrapers (linktree, komi, pillar, linkme) without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The confirm=true prerequisite and the cache-vs-live tradeoff imply usage conditions, but there is no explicit when-to-use vs. when-to-prefer-alternatives guidance and no mention of the sibling page tools (linktree_linktree_page etc.). Usage is implied rather than stated.

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

linkedin_ad_library_ad_detailsAd DetailsA

Retrieves detailed information about a specific LinkedIn ad by URL. Returns id, description, headline, adType, advertiser, and targeting with language, location, and audience criteria. Also includes totalImpressions, impressionsByCountry, adDuration, startDate, and endDate. Date and impression fields are nullable when LinkedIn does not expose them on the public ad page. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The url of the ad
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false present, the description usefully adds that it 'potentially consumes paid API credits,' that confirm=true is required, and that these read-like POST requests do not publish to social platforms -- directly reconciling the apparent write intent with the annotations. It also discloses nullable date/impression fields, which the annotations do not cover.

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?

Purpose is front-loaded in the first sentence, followed by return fields and then behavioral caveats. The enumeration of returned fields is somewhat list-heavy but each clause is informative and there is no filler.

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?

There is no output schema, so enumerating the returned fields (id, description, headline, adType, targeting, impressions, dates) is necessary and done. Combined with the credit/confirm caveats and nullability note, an agent has enough to call it correctly, though the relationship to the search sibling remains unstated.

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 100%, so all three parameters are already documented in the schema; the description mostly restates the confirm=true requirement rather than adding new syntax or format meaning. Baseline 3 is appropriate when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (retrieves detailed info about a specific LinkedIn ad) and anchors the retrieval on a URL, which clearly separates it from the same-platform search sibling linkedin_ad_library_search_ads. It does not explicitly name that sibling or state that search must precede detail retrieval, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (you must have a specific ad URL, and confirm=true is required) and flags credit consumption, but it never says when to use this versus linkedin_ad_library_search_ads or the Facebook/Google ad-detail siblings. Usage is inferable from the URL requirement rather than stated.

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

linkedin_ad_library_search_adsSearch AdsA

Searches the LinkedIn Ad Library by company name, keyword, or companyId with optional country and date filters. Custom date filtering requires both startDate and endDate. LinkedIn accepts dates from the date one year ago through yesterday. Each ad includes id, description, headline, adType, advertiser, targeting details, image or video URLs, totalImpressions, and impressionsByCountry. Date and impression fields are nullable when LinkedIn does not expose them on the public ad page. Supports pagination via paginationToken. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`company`	No	The company name to search for. 'Microsoft' for example
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`endDate`	No	End date in YYYY-MM-DD format. Must be used with startDate and cannot be today or a future date.
`keyword`	No	The keyword to search for
`companyId`	No	The company id to search for
`countries`	No	Comma separated list of countries. Example: US,CA,MX
`startDate`	No	Start date in YYYY-MM-DD format. Must be used with endDate and cannot be earlier than the date one year ago.
`paginationToken`	No	Pagination token to paginate through results

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description's credit-consumption warning, confirm=true requirement, and the clarification that the read-like POST does not publish to social platforms add real behavioral value. Nullability of date and impression fields is also disclosed, which the annotations do not cover.

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 what the tool does and its filters, followed by constraints, return fields, and cost/auth caveats. It is slightly dense across four sentences, but each carries distinct information (dates, credit cost, nullability, pagination) and none is filler.

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 credit-consuming tool with no output schema, the description covers return shape (id, headline, adType, advertiser, targeting, media URLs, impressions), nullability, pagination, and credit/auth requirements. Rate limits or pagination termination behavior are not mentioned, but the essentials are present.

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 100%, so every parameter is already documented in the input schema; baseline is 3. The description restates the startDate/endDate pairing constraint and paginationToken usage, which largely duplicates what the schema already says rather than adding new syntax or semantics.

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?

The opening sentence names a specific verb (Searches) and a scoped resource (LinkedIn Ad Library ads), plus the three query modes (company, keyword, companyId). An agent can distinguish this from linkedin_ad_library_ad_details, which retrieves a single known ad rather than searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states operational prerequisites (confirm=true required, startDate/endDate must be used together, LinkedIn's one-year-to-yesterday window), which is useful. However, it never states when this tool is preferable to alternatives such as linkedin_ad_library_ad_details or linkedin_search_posts, leaving routing to inference.

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

linkedin_company_pageCompany PageA

Fetches a LinkedIn company page with details including name, description, logo, cover image, slogan, location, headquarters, employee count (headcount/staff size), website, industry, company type, founded year, specialties, funding rounds with investors, featured employees, recent posts, and similar company pages. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the LinkedIn company page to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which would normally read as a mutating call; the description resolves that ambiguity by explaining these are 'read-like POST requests' that do not publish to social platforms. It also discloses the credit cost and the confirm gate, adding real behavioral context beyond the annotations. It stops short of describing rate limits or whether repeated calls are billed separately.

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 verb and resource, then the long field enumeration, then the critical operational constraints. The field list is lengthy but earns its place because there is no output schema; the only real cost is that the operational warnings (credits, confirm) sit after it instead of before.

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?

With no output schema and full annotation coverage, the description compensates well by enumerating returned fields and flagging the credit/confirm requirements. It is missing only the expected format of the url input (full profile URL vs handle) and any note on caching or repeat-call billing.

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 100%, so url, account, and confirm are already documented in the schema. The description echoes the confirm/credit requirement but adds no syntax, format, or validation detail beyond what the schema provides. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetches') and resource ('LinkedIn company page') and enumerates the returned fields in detail, which is unusually concrete. However, it never names the nearest siblings (linkedin_person_profile, linkedin_company_posts) to disambiguate scope, so the agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Prerequisites are given clearly: it consumes paid credits and requires confirm=true. There is no guidance on when to choose this over linkedin_person_profile or linkedin_company_posts, so usage context is only implied by the tool name.

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

linkedin_company_postsCompany PostsA

Retrieves paginated posts from a LinkedIn company page, including each post's URL, ID, publication date, and full text content. Supports page-based pagination up to a maximum of 7 pages due to a LinkedIn platform limitation. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the LinkedIn company page to get
`page`	No	The page number to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, but the description adds material context beyond them: it consumes paid API credits, needs confirm=true, caps at 7 pages due to a platform limit, and clarifies that the read-like POST does not publish to social platforms. This resolves the non-obvious readOnlyHint=false flag, which is genuinely useful. It stops short of describing error or rate-limit behavior beyond the page cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action and return shape, then constraints, then the cost/confirm caveat. No filler.

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?

No output schema exists, but the description enumerates the returned fields and covers cost, confirmation, and pagination limits, which is enough for correct invocation. Minor gaps remain around error behavior and what happens past the 7-page cap.

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 100%, so all four parameters are already documented in the schema. The description reinforces page-based pagination and the confirm requirement but adds no syntax or format detail beyond what the schema states, so baseline 3 is correct.

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+resource ('Retrieves paginated posts from a LinkedIn company page') and enumerates the returned fields (URL, ID, publication date, full text). This clearly distinguishes it from siblings like linkedin_company_page (page metadata) and linkedin_post (single post).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a prerequisite ('requires confirm=true') and a hard scope limit (max 7 pages), which shape how to call it. However, it never names an alternative or states when to pick this over linkedin_company_page or linkedin_post, so routing between siblings is left to inference.

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

linkedin_person_profilePerson's ProfileA

Retrieves a person's public LinkedIn profile data, including their name, photo, location, follower count (followers), about/bio summary, recent posts, work experience, education, articles, activity feed, publications, projects, recommendations, and similar profiles. Only returns publicly available information visible in an incognito browser. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the LinkedIn profile to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.2/5.0

Behavior4/5

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

With readOnlyHint=false and idempotentHint=false already declared, the description adds real value by clarifying that these read-like POST requests do not publish to social platforms and that the call consumes paid API credits gated by confirm=true. It stops short of describing rate limits, error modes, or what happens on retry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core capability and return fields before the operational constraints. No filler, every clause carries information.

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?

There is no output schema, and the description compensates well by enumerating the returned fields, plus it covers the credit/confirmation gating. Missing only explicit sibling routing guidance for a tool sitting among many LinkedIn and other-platform profile tools.

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 100%, so the schema already explains url, account, and confirm. The description only reinforces the confirm=true requirement, adding marginal meaning beyond the structured fields; baseline 3 applies.

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 (Retrieves) and resource (a person's public LinkedIn profile) and enumerates the returned data fields. It is clearly distinguishable from siblings such as linkedin_company_page or linkedin_post, which cover different LinkedIn entities.

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 clear context for use: only publicly available incognito-visible data, and requires confirm=true for the approved credit-consuming call. It does not explicitly name alternatives (e.g., linkedin_company_page for organizations) or state when not to use it, so it falls short of a 5.

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

linkedin_postPostA

Fetches a single LinkedIn post or article, returning the title, headline, full description text, author info with follower count, publication date, like count (reactions), comment count, and individual comments. For public feed posts, activityUrn and contentUrn expose LinkedIn's public activity and underlying share or ugcPost URNs when present; either can be null when LinkedIn does not expose it. Also includes related articles from the same author in moreArticles. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the LinkedIn post to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, but leave ambiguous whether a POST has side effects. The description resolves this ('Read-like POST requests do not publish to social platforms') and adds credit consumption plus the confirm=true gate – real behavioral context beyond the annotations. It stops short of describing pagination or comment-volume limits.

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 core action and returned fields, then the URN caveat and the cost/confirm constraint. The URN sentence is dense and somewhat niche, but every sentence carries usable information.

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?

With no output schema, the description correctly carries the burden of enumerating return fields (title, author, reactions, comments, moreArticles), and it covers the credit/confirm constraint. Only the response shape for edge cases (null URNs is covered; error behavior is not) remains thin.

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 100%, so all three parameters are already documented. The description reinforces confirm=true and clarifies the account credential scoping indirectly, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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 (fetches) and resource (a single LinkedIn post or article), and enumerates the returned payload. The 'single' framing cleanly separates it from linkedin_search_posts, linkedin_company_posts, and linkedin_post_transcript without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The confirm=true requirement and the credit-cost warning give real invocation context, and the URL parameter implies the use case. But it never says explicitly when to pick this over linkedin_post_transcript or linkedin_search_posts, nor what happens if confirm is omitted.

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

linkedin_post_transcriptPost TranscriptA

Fetches the transcript from a LinkedIn post video when LinkedIn exposes one publicly. Returns null with transcriptNotAvailable when the post has no transcript, and only deducts credits when a transcript is returned. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the LinkedIn post to get the transcript from
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses the failure payload (null with transcriptNotAvailable), the billing rule (credits deducted only when a transcript is returned), the confirm=true requirement, and explains that the read-like POST does not publish to social platforms. That last point usefully reconciles the non-readOnly annotation with the actual side-effect profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: purpose and availability constraint first, then the return/billing/confirmation behavior. Every clause carries information; nothing is repeated from the schema or annotations.

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?

With no output schema, the description correctly explains the null/transcriptNotAvailable case and the credit semantics, which an agent needs. It stops short of describing the success payload's shape or any rate limits, a minor gap for a credit-consuming call.

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, and the description adds real meaning for confirm (must be true for the specific approved credit-consuming call) and the credit consequences of the url call. The account parameter's semantics are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: fetching a video transcript from a LinkedIn post, with the scope qualifier 'when LinkedIn exposes one publicly'. It clearly separates itself from the generic linkedin_post sibling by naming the artifact (transcript) rather than the post, though it never explicitly names a sibling to route against.

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 conditions: works only when LinkedIn exposes a public transcript, requires confirm=true, and consumes paid credits. It doesn't name an alternative tool for the no-transcript case or point to linkedin_post for non-video content, so the when-not branch is only partially covered.

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

linkedin_search_postsSearch PostsA

Finds public LinkedIn posts, feed updates, and Pulse articles by keyword using Google Search, then returns post details such as description, author, media, images, like count, comment count, and published date when LinkedIn exposes them publicly. Results depend on what Google has indexed, so this is best-effort and not a complete LinkedIn-native search. Use date_posted for recent posts and pass the returned cursor to fetch the next page. Cursors are limited to pages 1 through 11; cursor 12 or greater returns a 400 response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Keyword or phrase to search for in public LinkedIn posts
`cursor`	No	The cursor returned from the previous response. The maximum cursor is 11; cursor 12 or greater returns a 400 response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`date_posted`	No	Date posted filter based on Google-indexed results

TDQS

A4.2/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, but they don't clarify that this is a read-like POST that consumes paid credits and requires a confirm flag. The description adds these valuable caveats ('Potentially consumes paid API credits; requires confirm=true', 'Read-like POST requests do not publish to social platforms'), providing essential behavioral context beyond annotations.

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-loads scope and mechanism, then details results, pagination limits, and credit/confirmation requirements. Two paragraphs are efficient. The sentence 'Cursors are limited to pages 1 through 11; cursor 12 or greater returns a 400 response' is slightly redundant with the schema description.

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?

Given no output schema and a potentially expensive external call, the description covers all necessary aspects: source mechanism, limitations, pagination, credit consumption, and side-effect-free nature. An agent has enough to decide when and how to call it correctly.

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 100%, so the schema already documents all parameters. The description explains date_posted usage and cursor limits, but doesn't add format or syntax details beyond what the schema provides.

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?

Names a specific verb (Finds) and resource (public LinkedIn posts, feed updates, Pulse articles), plus describes the mechanism (Google Search) and highlights an important limitation (best-effort, not native search). This differentiates it from sibling linkedin_post and linkedin_company_posts.

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?

States when to use date_posted ('for recent posts') and provides the cursor pagination workflow. However, it does not explicitly name alternatives like linkedin_company_posts or linkedin_post, nor does it clearly say when to avoid this tool.

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

linkme_profileProfileA

Retrieves a Linkme profile by URL, including identity, social links, and contact details. Returns profile with id, firstName, username, bio, profileVisitCount, profileImage, verifiedAccount, and isAmbassador flag. Also includes infoLinks (email addresses) and webLinks, an array of categorized social platform links (Spotify, Instagram, YouTube, Twitter, Facebook, and more) each with linkValue and faceValue. Contact fields come from the submitted public Linkme profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Linkme profile URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior4/5

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

With readOnlyHint=false and idempotentHint=false, the annotations alone would mislead an agent into expecting a mutating call. The description resolves this by disclosing that it is a read-like POST that 'do not publish to social platforms,' and adds credit consumption and the confirm=true gate. It stops short of documenting rate limits or failure modes.

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-loads the core action before the field inventory, and each clause carries payload or billing information. The removal-policy sentence is slightly tangential but still operationally relevant, so the tool remains reasonably tight.

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?

With no output schema, the description carries the return-value burden and does so by naming the identity fields, infoLinks, and categorized webLinks. Combined with the credit/confirm caveats and the schema's cache documentation, an agent has enough to call it correctly, though error and pagination behavior are unaddressed.

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 description coverage is already 100%, so a 3 is the floor, and the description earns above it by explaining the practical meaning of confirm=true ('Potentially consumes paid API credits') and reinforcing the url parameter's role. The account and cache_max_age parameters are left 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 verb and resource ('Retrieves a Linkme profile by URL') and enumerates the returned payload (identity, social links, contact details, flags). This clearly separates it from sibling link-in-bio scrapers such as linktree_linktree_page, komi_komi_page, and linkbio_linkbio_page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via the URL-parameter premise and notes the confirm=true requirement, but it never states when to prefer linkme_profile over the other link-in-bio or social-profile siblings, nor any exclusion conditions. Usage is inferable rather than explicit.

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

linktree_linktree_pageLinktree pageA

Scrapes a Linktree page by URL, extracting the creator's profile and all their links. Returns id, username, profilePictureUrl, description, verticals, timezone, and links — an array of link objects each with id, type, title, and url. Also includes detected social accounts (instagram, tiktok, spotify, youtube, soundcloud, apple_music) and email_address. Contact fields come from the submitted public Linktree page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to Linktree page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare openWorldHint=true, destructiveHint=false, idempotentHint=false, readOnlyHint=false, and the description goes further by disclosing credit consumption, the confirm=true gate, and that these read-like POSTs do not publish to social platforms. The removal-request/email path and the source of contact fields add genuine context. This is a solid, non-contradictory disclosure that enriches rather than restates the annotations.

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 core purpose, then the return shape, then behavioral caveats. The return-field enumeration is verbose, but since no output schema exists it earns its place. No filler or redundancy across the operational sentences.

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?

With no output schema, the description compensates by enumerating the returned fields (profile, links array, social accounts, email). Combined with the credit/confirm/annotation coverage, an agent has enough to invoke it correctly; only the absence of an explicit alternative-selection note keeps it from a 5.

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 100%, so url, account, confirm, and cache_max_age are already documented in the schema; baseline is 3. The description reinforces the confirm/credit constraint but adds no syntax or format detail beyond the schema for any parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (scrapes) and resource (a Linktree page by URL) and enumerates the extracted content (profile, links, social accounts, email). It clearly delimits what this tool covers, though it never names the near-siblings (linkbio_linkbio_page, komi_komi_page, pillar_pillar_page) that an agent might confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (you supply a Linktree URL) and adds the operational preconditions 'requires confirm=true' and 'potentially consumes paid API credits', which is meaningful guidance. However, it gives no explicit when-to-use/when-not framing relative to the other page-scraper siblings, leaving routing to inference.

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

list_accountsList configured accountsA

Read-onlyIdempotent

List private account labels, default selection and configured token method. No credentials, token paths or account content; no network request.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it confirms no credentials, token paths, or account content are returned, and that no network request is made.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences front-load the core scope and then immediately clarify the negative behavior. Every phrase contributes useful information with no filler.

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 zero-parameter, read-only listing tool with no output schema, the description adequately covers the returned concepts and explicitly rules out sensitive data and network activity. It stops short of describing result ordering, formatting, or pagination, but those may not apply or may be self-evident.

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?

The tool takes zero parameters, so there are no parameter semantics to clarify. Per the rubric, a zero-parameter tool has a baseline of 4, and the description does not need to compensate for undocumented inputs.

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?

The description gives a specific verb and resource (list accounts) and enumerates the exact scope: private account labels, default selection, and configured token method. Its exclusions also implicitly distinguish it from broader siblings like get_account or get_current_token, which would expose account content or credentials.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating exactly what metadata the tool surfaces, but it never explicitly says when to call this instead of alternatives such as get_account or get_current_token. The 'No credentials...' clause scopes the tool, yet no named alternative or when-not condition is given.

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

pillar_pillar_pagePillar pageA

Scrapes a Pillar page by URL, extracting the creator's profile, social links, and products. Returns id, first_name, last_name, email, location, and social accounts (tiktok, spotify, twitter, youtube, facebook, linkedin, instagram, and more). Also includes links with click counts and products with title, price, description, and image. Contact fields come from the submitted public Pillar page. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL to Pillar page
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false the annotations alone imply a mutating call, so the clarification that 'Read-like POST requests do not publish to social platforms' adds real value. It also discloses paid credit consumption, the confirm=true gate, and a data-removal contact path. It does not cover rate limits or response caching beyond what the schema param already says.

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?

Purpose and scope are front-loaded, and the credit/confirm caveat is placed at the end where it belongs. Slightly padded by the long enumeration of social accounts ('and more') and a compliance note that could be tighter, but no sentence is wasted.

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?

There is no output schema, so the description must carry the return shape – and it does, listing id, names, email, location, social accounts, links with click counts, and product fields. Credit/confirm/caching/compliance context is present; only cross-sibling disambiguation is missing.

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 100%, so url, account, confirm, and cache_max_age are fully documented in the schema itself. The description adds nothing to parameter meaning (its field list describes outputs, not inputs), so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (scrapes) and resource (Pillar page by URL) and enumerates what is extracted: creator profile, social links, and products. An agent can distinguish it from the TikTok/Instagram profile tools by resource name, but it never names its true siblings (linktree_linktree_page, komi_komi_page, linkme_profile, amazon_shop_amazon_shop_page) to differentiate among the 'bio-link page' family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear (call it when you have a Pillar page URL), and it discloses the confirm=true precondition plus credit cost. However, there is no explicit routing guidance comparing it to the Linktree/Komi/Linkbio/Linkme alternatives that an agent would otherwise confuse it with.

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

pinterest_boardBoardA

Fetches a paginated list of pins from a Pinterest board by URL, returning each pin's id, description, title, images, board info, pin_join annotations, and aggregated_pin_data. Supports pagination via cursor and a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the board to get
`trim`	No	Set to true for a trimmed down version of the response
`cursor`	No	The cursor to get the next page of results
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Goes beyond annotations by disclosing that the call consumes paid API credits, requires confirm=true, and clarifies that the read-like POST does not publish to social platforms — directly addressing the readOnlyHint=false signal. Missing rate-limit or retry behavior keeps it from 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?

Two dense sentences, front-loaded with the primary action and return fields, then the credit/confirm constraint. No wasted text, though the return-field enumeration is long.

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?

With no output schema, the description usefully enumerates the returned fields and covers the credit cost and confirm requirement. Gaps remain around the account parameter and pagination termination, but the tool is callable correctly from what is given.

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 100%, so the baseline is 3. The description only lightly reinforces cursor (next page) and trim (lighter response) without adding syntax or default behavior beyond the schema, and says nothing about the account credential parameter.

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?

Specific verb+resource+scope: fetches a paginated list of pins from a Pinterest board by URL, and enumerates returned fields. It is clearly distinguishable from siblings like pinterest_pin (single pin) and pinterest_user_boards (boards of a user).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the pagination mechanism (cursor) and the trim option, and warns that confirm=true is required, which implies when the call is valid. But it never compares this tool against siblings such as pinterest_search or pinterest_pin, nor states when a board fetch is preferred.

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

pinterest_pinPinA

Fetches detailed information about a single Pinterest pin by URL, returning title, description, link, dominantColor, originPinner, pinner, images at multiple resolutions (imageSpec_236x through imageSpec_orig), and pinJoin with visual annotations. Supports a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Pinterest pin URL
`trim`	No	Set to true for a trimmed down version of the response
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior4/5

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

Adds context annotations don't carry: paid API credit consumption, the mandatory confirm=true gate, and the clarification that this read-like POST does not publish to social platforms (which explains the readOnlyHint=false annotation rather than contradicting it). Cache behavior is left entirely to the schema, so it isn't fully complete but is well above the annotation baseline.

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?

Two sentences, front-loaded with the core action and its return payload, then the cost/confirm caveat. Slightly dense in the field enumeration but each item maps to a distinct part of the response, so little is wasted.

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?

With no output schema, the description usefully enumerates the return payload and offsetting details like trim, credits, and confirm. It omits pagination/error behavior and the caching interaction, which is the main remaining gap for a paid, confirm-gated call.

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 100%, so the schema already defines url, trim, account, confirm, and cache_max_age. The description only restates the trim option and mentions confirm, adding no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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 precise verb (fetches) plus resource (a single Pinterest pin) and pins down the identifier type (by URL). It enumerates the returned fields and distinguishes itself from the sibling pinterest_search/pinterest_board tools by operating on exactly one pin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives operational guidance (confirm=true required, trim option, credit cost) but never states when to choose this over pinterest_board or pinterest_search, nor any exclusion beyond the by-URL case implied by the schema. Usage is inferable from the resource scope but not made explicit.

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

pinterest_searchSearchA

Searches Pinterest for pins matching a query, returning results with id, url, title, description, images, link, domain, board info, and pinner details. Supports pagination via cursor and a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`query`	Yes	Search query
`cursor`	No	Cursor
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Adds real context beyond the annotations: it warns that calls may consume paid API credits, requires confirm=true, and pre-empts concern by noting the read-like POST does not publish to social platforms. This meaningfully clarifies the readOnlyHint=false annotation, though it omits rate-limit or partial-failure behavior.

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?

Two sentences, front-loaded with the core action; the return-field list is somewhat long but legitimately informative since there is no output schema. Every sentence carries weight, though the field enumeration could be trimmed.

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?

With no output schema, the description usefully covers return fields, and it addresses pagination and the confirm/credit requirement. Given a five-parameter read tool, this is nearly complete; only edge behaviors and error handling are absent.

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 100%, so the schema already documents query, cursor, trim, account, and confirm. The description only echoes cursor pagination and the trim option, adding no syntax or format detail beyond the structured fields, which lands on the baseline.

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 ('Searches Pinterest for pins matching a query') and enumerates the returned payload fields, making the scope unambiguous next to siblings like pinterest_pin, pinterest_board, and pinterest_user_boards. An agent can distinguish this wide search from the narrower pin/board lookups without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('matching a query', pagination via cursor, trim for lighter responses) but never names an alternative or states when to prefer pinterest_search over pinterest_pin or a board-level tool. Conditions like confirm=true are stated, but the core use-vs-alternative routing is left to inference.

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

pinterest_user_boardsUser BoardsA

Fetches a paginated list of boards for a Pinterest user, returning each board's name, url, description, pin_count, follower_count, owner info, cover_images, and created_at. Supports pagination via cursor and a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	Yes	The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/)
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only declare the generic profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds the operationally important facts that credits are consumed, confirm=true is mandatory, responses are paginated, and even though it is a POST it does not publish to social platforms. It does not explain rate limits, cursor lifetime, or error behavior, so it stops short of 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?

Two tightly packed sentences with the returned fields and pagination front-loaded, followed by the cost/confirmation constraint. Every clause carries information, with only the unsupported 'cursor' mention detracting slightly.

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?

There is no output schema, so enumerating the returned fields (name, url, pin_count, follower_count, owner, cover_images, created_at) plus pagination and trim meaningfully fills the gap. The credit/confirm requirement is also covered. Left slightly incomplete by the unexplained cursor and the absence of guidance on how to retrieve subsequent pages.

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 coverage is 100%, so handle, account, confirm and trim are already documented in the schema, and the description mostly restates trim and confirm. It also references 'pagination via cursor', yet no cursor parameter exists in the schema, so this adds a small amount of ambiguity rather than clarifying a parameter. Baseline 3 applies when the schema does the heavy lifting.

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 (fetch a paginated list of boards for a Pinterest user) and enumerates the returned fields, which cleanly distinguishes it from the sibling pinterest_board (single board) and pinterest_search. An agent can identify exactly what this returns without opening the schema.

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 preconditions for calling it: paid API credits are involved and confirm=true is required, plus notes the trim option for lighter responses. It does not, however, explicitly contrast the tool with pinterest_board or pinterest_search or state when a user-board lookup is the wrong choice, so 4 rather than 5.

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

reddit_postPostA

Retrieves public Reddit post details by URL without fetching or returning comments. Returns the text post body in selftext when present, plus the title, author, subreddit, score, upvote ratio, comment count, timestamps, permalink, and post flags. Accepts canonical Reddit post URLs and Reddit mobile share URLs. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Reddit post URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial context beyond annotations: it discloses that the call may consume paid API credits, that confirm=true is mandatory, and clarifies that the read-like POST does not publish to social platforms, justifying the readOnlyHint=false annotation rather than merely restating it.

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 purpose and return fields, then a short second block for the credit/confirm caveat. Dense but every sentence carries information; the enumerated return-field list is slightly long yet useful in the absence of an output schema.

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?

With no output schema, the description compensates by naming the returned fields (selftext, title, author, subreddit, score, upvote ratio, comment count, timestamps, permalink, flags). Combined with URL format and credit/confirm requirements, an agent has everything needed to invoke it correctly.

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 adds real value: it specifies accepted URL formats for 'url' and explains the credit-consuming semantics behind 'confirm'. The 'account' parameter's credential-selection meaning 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 verb+resource+scope: 'Retrieves public Reddit post details by URL without fetching or returning comments.' The explicit exclusion of comments distinguishes it cleanly from siblings like reddit_post_comments and reddit_post_comments_post.

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?

Clear context is given (single post lookup by URL, excludes comments, accepts canonical and mobile share URLs), which implicitly routes comment-seeking agents to reddit_post_comments. It never names that alternative or states explicit when-not-to-use conditions, so it stops short of a 5.

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

reddit_post_commentsPost CommentsA

Retrieves comments and post details from a Reddit post by URL. Returns the post with title, author, score, ups, upvote_ratio, num_comments, and created_utc, plus a comments array where each comment includes author, body, body_html, score, created_utc, parent_id, permalink, and nested replies. Both GET and POST are supported. Use GET for normal requests. Pass one opaque cursor exactly as returned by more.cursor or replies.more.cursor to load the next page. Cursor batching and comma-separated cursor values are not supported. If an opaque cursor becomes too large after extensive pagination, use POST and send the same parameters in the JSON body. Supports cursor-based pagination for loading more comments and a trim parameter for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Reddit post URL
`trim`	No	Set to true for a trimmed down version of the response
`cursor`	No	One opaque cursor returned by the previous response to get more comments or replies. Do not combine multiple cursors.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior5/5

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

With readOnlyHint=false and idempotentHint=false declared, the description goes well beyond the annotations: it warns of paid API credit consumption, mandates confirm=true, and explicitly reconciles the read-like POST nature ("do not publish to social platforms"). It also discloses a real constraint beyond the schema, that cursor batching and comma-separated cursors are unsupported.

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?

The first sentence of each block is front-loaded with the essential fact, and the return-field list is dense but useful. The trailing credit/confirm sentence sits apart from the flow of the rest and reads slightly appended, keeping it short of a 5.

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?

There is no output schema, yet the description enumerates the post fields and per-comment fields (including nested replies), plus pagination, trim, auth/credit, and confirm requirements. Nothing an agent needs to call this 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 adds genuine cursor semantics not evident from the schema alone: one opaque cursor exactly as returned by more.cursor/replies.more.cursor, no batching, and the POST fallback for oversized cursors. It also clarifies trim's effect on response weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("Retrieves comments and post details from a Reddit post by URL") and enumerates the returned fields, so the agent immediately knows what it gets. It does not, however, distinguish itself from the closely-named siblings reddit_post and reddit_post_comments_post, leaving potential ambiguity inside the reddit family.

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?

It gives concrete operating guidance: use GET for normal requests, switch to POST when an opaque cursor grows too large, pass exactly one cursor with no batching, and requires confirm=true. What it lacks is an explicit statement of when to pick this over reddit_post or reddit_post_comments_post.

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

reddit_post_comments_postPost CommentsA

ParametersJSON Schema

Name	Required	Description
`url`	No	Reddit post URL
`trim`	No	Set to true for a trimmed down version of the response
`cursor`	No	One opaque cursor returned by the previous response to get more comments or replies. Do not combine multiple cursors.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`payload`	No	Complete JSON request body instead of body flags. Preserves current endpoint fields and values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.3/5.0

Behavior4/5

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

Beyond the annotations it discloses the two traits that matter most operationally: the call consumes paid API credits and requires confirm=true, and read-like POSTs do not publish to social platforms (which explains the readOnlyHint=false). It also documents pagination constraints (no cursor batching or comma-separated cursors). It stops short of describing error/failure behavior or credit amounts.

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?

Purpose and return shape are front-loaded, and the long field list earns its space because there is no output schema. It is somewhat over-packed: pagination and cursor rules, GET/POST guidance, trim, and credit/confirm notes are run together in a single block, and the credit warning is appended at the end rather than near the top where a cost-bearing requirement would be more visible.

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?

With no output schema, no required parameters, and a nested payload object, the description does the heavy lifting well: it describes both the post fields and the comment object fields including nested replies, plus pagination and credit behavior. Only edge behavior (invalid URL, exhausted cursor, interaction of payload vs payload_file) is left undocumented.

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 adds real semantics the schema lacks: cursor must be a single opaque value taken exactly from more.cursor or replies.more.cursor, cursor batching is unsupported, POST should carry the same parameters in the JSON body, and trim exists to lighten responses. That is meaningful guidance beyond the field descriptions.

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?

The opening sentence gives a specific verb (retrieves) and resource (comments and post details from a Reddit post by URL), and the scope statement distinguishes it from the post-only sibling reddit_post. The returned-field enumeration reinforces that this is the comments-plus-post tool rather than a plain post fetch.

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?

It gives explicit conditional guidance on the GET vs POST path ("Use GET for normal requests", switch to POST when the opaque cursor grows too large) and on when to use trim. It does not, however, name the sibling tools (reddit_post, reddit_post_transcript) an agent would otherwise consider, so routing between Reddit tools is still left to inference.

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

reddit_post_transcriptPost TranscriptA

Gets the transcript from a Reddit video post or direct v.redd.it URL when Reddit exposes a VTT caption file. Returns the raw WebVTT in raw_vtt plus a parsed plain-text transcript. If Reddit does not expose captions for the video, transcript is null and transcriptNotAvailable is true. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Reddit post URL or direct v.redd.it video URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	2 letter language code. Defaults to en.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.2/5.0

Behavior4/5

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

Adds substantial behavioral context beyond the annotations: potential credit consumption, the confirm=true gate, and a clarification that 'read-like POST requests do not publish to social platforms' which usefully reconciles the readOnlyHint=false annotation with expected read-like semantics. Return-shape behavior (null transcript) is also disclosed; no contradiction with annotations.

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 core action and return behavior, then credit/confirm constraints. Every sentence carries information, though the url restatement slightly overlaps the schema.

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?

With no output schema, the description proactively explains the return values (raw_vtt, transcript, transcriptNotAvailable), which is exactly the missing structured information an agent needs, and it covers the credit/confirmation requirement. Complete for this tool's complexity.

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 coverage is 100%, so the parameters (url, account, confirm, language, cache_max_age) are already fully documented in the schema. The description only restates the url semantics (Reddit post or v.redd.it URL) already present in the schema, adding no new syntax or format detail, so the baseline 3 applies.

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 ('Gets the transcript from a Reddit video post or direct v.redd.it URL'), scoping it to Reddit/v.redd.it and thus clearly separating it from the many sibling *_transcript tools (tiktok_transcript, youtube_transcript, instagram_transcript, etc.). The added condition 'when Reddit exposes a VTT caption file' further sharpens the purpose.

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 clear context: it applies to Reddit video posts or direct v.redd.it URLs, requires confirm=true, and consumes potential paid credits. It explains the failure mode (transcript null / transcriptNotAvailable true) rather than routing to an alternative sibling, so the when-not scenarios are covered but no explicit alternative tool is named.

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

reddit_searchSearchA

Searches across all of Reddit for posts or comments matching a query. Set filter to posts (the default) or comments. Post results include title, author, selftext, subreddit, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, and is_video. Comment results include the matching body, author, votes, timestamps, comment URL, parent relationship, and post/subreddit context. Comment searches support relevance, new, and top sorting. Timeframe filtering applies to post searches. Pagination uses the after token, and trim returns a lighter response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`sort`	No	Sort by. Comment search supports relevance, new, and top; comment_count is for post search only.
`trim`	No	Set to true for a trimmed down version of the response
`after`	No	Used to paginate to next page
`query`	Yes	Search query
`filter`	No	Search posts or comments
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`timeframe`	No	Post search timeframe

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=false the description usefully explains the apparent contradiction by clarifying that 'Read-like POST requests do not publish to social platforms,' and it adds the credit-consumption and confirm=true requirements plus pagination via the after token and the trim lighter-response option. That is meaningful context beyond the annotations, though rate limits and error behavior are still unstated.

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?

Purpose is front-loaded in the first sentence, followed by result-field detail and operational constraints. It is dense but each clause carries information, with only minor redundancy against the schema in the sort/timeframe sentences.

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?

There is no output schema, and the description compensates by enumerating the post and comment result fields. Combined with the credit/confirm constraint and pagination note, an agent has enough to invoke it correctly, though the absence of any explicit sibling comparison leaves a small gap.

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 100%, so the schema already documents all eight parameters. The description largely restates schema semantics (sort constraints, timeframe, after, trim) rather than adding format or interaction detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Searches... for posts or comments matching a query') and scopes it to 'all of Reddit,' which implicitly sets it apart from reddit_subreddit_search. It stops short of naming that sibling explicitly, so an agent must infer the boundary rather than being told it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real routing conditions: filter selects posts vs comments, comment search supports relevance/new/top, timeframe applies to post searches only, and confirm=true is required. However, it never states when to prefer this tool over reddit_subreddit_search, reddit_subreddit_posts, or other search tools, so guidance is implied rather than explicit.

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

reddit_subreddit_detailsSubreddit DetailsA

Retrieves metadata about a subreddit by name or URL. The subreddit name must be case-sensitive. Returns display_name, description, subscribers, weekly_active_users, weekly_contributions, rules, icon_img, header_img, advertiser_category, submit_text, and created_at. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Subreddit URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`subreddit`	No	Subreddit name. MUST be case sensitive. So 'AskReddit' not 'askreddit'.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior4/5

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

Adds genuinely useful behavior beyond annotations: it may consume paid credits, requires confirm=true, and clarifies that the read-like POST does not publish to social platforms. This offsets the potentially confusing readOnlyHint=false and idempotentHint=false annotations without contradicting them.

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 purpose, then the return field list, then the credit/confirm constraints. The field enumeration is long but earns its place given there is no output schema. No filler sentences.

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?

With no output schema, listing the returned fields is valuable, and the credit/confirm/case-sensitivity notes cover the main invocation risks. Minor gap: it does not explain caching behavior beyond what the cache_max_age schema already says.

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 coverage is 100%, so the baseline is 3. The description reinforces the case-sensitivity rule for subreddit and the name-or-URL input dimension, but adds little syntax or format detail beyond what the schema already documents.

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 ('Retrieves metadata about a subreddit') and enumerates the returned fields, so an agent can immediately distinguish it from siblings like reddit_subreddit_posts or reddit_subreddit_search. Scope (by name or URL) is also declared up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives operative constraints (case-sensitive name, requires confirm=true, credit cost) but never states when to prefer this over reddit_subreddit_search or reddit_subreddit_posts. Usage is implied by the tool name rather than explicitly routed.

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

reddit_subreddit_postsSubreddit PostsA

Fetches posts from a subreddit with sorting and filtering options. Each post includes title, author, link_flair_text when Reddit exposes it, selftext, score, ups, upvote_ratio, num_comments, created_utc, url, permalink, subreddit_subscribers, and is_video. Supports sort (best, hot, new, top, rising), timeframe filtering, pagination via the after token, and a trim parameter for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`sort`	No	Sort order
`trim`	No	Set to true for a trimmed down version of the response
`after`	No	After to get more posts. Get 'after' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`subreddit`	Yes	Subreddit name
`timeframe`	No	Timeframe to get posts from
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations mark readOnlyHint=false and openWorldHint=true, and the description helpfully explains the apparent tension: it discloses that the call is credit-consuming, requires confirm=true, and clarifies that read-like POSTs don't publish to social platforms. It also enumerates returned fields, adding real context beyond the annotations, though it omits caching interaction detail that the schema parameter hints at.

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?

The purpose is front-loaded in the first sentence, and the credit/confirm warning is appropriately placed. The long field enumeration is slightly dense but earns its place given there is no output schema.

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 an 8-parameter, credit-consuming tool with no output schema, the description covers the return fields, the confirm requirement, and the read-like POST semantics. It could say more about the caching/credit tradeoff, but it is otherwise sufficient to call correctly.

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 100%, so the schema already documents each parameter (sort enum, timeframe enum, after token, trim, confirm, account, cache_max_age). The description restates sort/timeframe/pagination/trim without adding format or interaction semantics beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Fetches posts from a subreddit') with scope (sorting/filtering), so the agent knows exactly what it returns. It does not differentiate from siblings like reddit_search or reddit_subreddit_search, which also surface Reddit content, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the resource name (fetch posts for a given subreddit) and the description notes available sort/timeframe options. However, it never says when to prefer this over reddit_search, reddit_subreddit_search, or reddit_post, leaving selection to inference.

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

reddit_subreddit_searchSubreddit SearchA

Searches within a specific subreddit for posts, comments, and media matching a query. Returns posts with title, votes, num_comments, url, and created_at; comments with author, body, votes, and parent post info; and media with title, media_type, image dimensions, and gallery_count. Supports sort, timeframe filtering, and cursor-based pagination. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`sort`	No	Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new
`query`	No	Search query to find matching content
`cursor`	No	Cursor to get more results. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`subreddit`	Yes	Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL)
`timeframe`	No	Timeframe to filter results

TDQS

A3.9/5.0

Behavior5/5

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

With readOnlyHint=false, an agent could wrongly assume a mutating/side-effecting call; the description resolves this by explaining that read-like POST requests do not publish to social platforms. It also discloses credit consumption and the confirm=true gate, which annotations do not cover.

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 core action, then return shape, then the credit/confirm caveat. The return-field enumeration is somewhat long but earns its place because there is no output schema. No filler sentences.

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?

With no output schema, describing the returned post/comment/media fields is necessary and done well, and pagination via cursor plus the credit/confirm gate are covered. Auth/account credential behavior is left entirely to the schema description, which is the only material gap.

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 100%, so every parameter (including the enum constraints on sort and timeframe) is already documented in the schema. The description adds sort/timeframe/pagination support at a high level but no syntax or semantics beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('searches') plus resource and scope ('within a specific subreddit') and enumerates the three content types returned (posts, comments, media). This distinguishes it from the broader reddit_search and from the listing-style reddit_subreddit_posts, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It establishes the operational precondition that the call 'requires confirm=true' and may consume paid credits, which is genuine usage guidance. However, it never says when to choose this over reddit_search or reddit_subreddit_posts, so selection guidance among near-identical siblings is only implied.

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

research_batchRun an approved bounded research batchA

Run up to 20 explicitly supplied research calls sequentially in one selected private account. Validates the whole batch before any network call, refuses account overrides/recursion and stops on the first failure. max_calls is a request bound, never a credit or billing guarantee. No automatic retry; completed outcomes are retained. Requires confirm=true for this exact batch.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No
`confirm`	No
`requests`	Yes
`max_calls`	Yes

TDQS

A4.4/5.0

Behavior5/5

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

Annotations declare the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description goes well beyond them: whole-batch validation before any network call, refusal of account overrides/recursion, stop-on-first-failure, no automatic retry, retention of completed outcomes, and the confirm gate. That is rich operational disclosure an agent needs for a fail-fast batch runner.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five tightly packed sentences, front-loaded with the core action and bound, then failure/confirmation semantics. No filler; every clause carries constraint or behavior information.

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 complex, non-idempotent batch tool with no output schema, the description covers validation, failure handling, retry policy, and confirmation. It could say more about the shape of returned partial results or error signaling, but an agent has enough to invoke it correctly.

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 description coverage is 0%, so the description must compensate, and it largely does: it explains max_calls as a request bound (not a billing guarantee), the confirm=true requirement for the exact batch, account as a single selected private account that cannot be overridden, and requests as up to 20 explicitly supplied calls. It adds real meaning over the bare schema, though it does not describe the requests item structure (tool/arguments).

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+resource (run a batch of research calls) with clear scope: up to 20 explicitly supplied calls, sequentially, in one selected private account. This is unmistakably distinct from all the single-request sibling tools, so an agent can identify it without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the usage context (batched multi-call execution against one account) and states the confirm=true prerequisite, but never explicitly says when to prefer this over issuing the sibling tools individually, nor when not to batch. Guidance is implied rather than stated.

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

rumble_channel_videosChannel VideosA

Gets videos from a Rumble channel by handle or URL. Returns channel metadata, videos, shorts, and a numeric cursor for the next page. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	Rumble channel URL. If you'd prefer to use the handle instead, use the handle parameter.
`cursor`	No	Cursor from the previous response. This is the next page number, like 2 or 3.
`handle`	No	Rumble channel handle. If you'd prefer to use the URL instead, use the url parameter.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already set readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds valuable context beyond them: credit consumption, the confirm=true requirement, and the clarification that 'read-like POST requests do not publish to social platforms,' which explains why a read operation is flagged non-readOnly. No return-format detail beyond the named fields, keeping it short of 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?

Three compact sentences, front-loaded with the core action before the operational caveats. Every sentence carries information; nothing is padding, though the credit/confirm caveat is essential rather than optional.

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?

With no output schema, the description usefully enumerates the return shape (channel metadata, videos, shorts, numeric cursor) and covers the credit/confirm gating. All five parameters are schema-documented, so the definition is nearly complete for a paged list tool; only explicit sibling routing is absent.

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 100%, so all five parameters are already documented in the schema. The description restates the handle/URL alternative and cursor-for-next-page meaning without adding syntax or constraints beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Gets videos from a Rumble channel') plus the input modes (handle or URL) and what is returned (metadata, videos, shorts). An agent can distinguish it from rumble_video and rumble_search by scope, but the description never names those siblings to make the boundary explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds the critical operating conditions 'Potentially consumes paid API credits; requires confirm=true,' which tells the agent how to call it safely. However, it gives no when-to-use-vs-alternative guidance (e.g., when to prefer rumble_video or rumble_search), so guidance is implied rather than routed.

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

rumble_commentsCommentsA

Gets all top level comments for a Rumble video by URL. Returns comment text, author, createdAt, createdAtText, likeCount, dislikeCount, and replyCount when comment bodies are public. If Rumble requires sign-in to view the comments, this endpoint returns HTTP 403 with error forbidden and does not charge credits. This is different from a public video with no comments, which returns a successful empty comments array.

Sign-in-required response example:

{
  "success": false,
  "credits_remaining": 100,
  "credits_charged": 0,
  "error": "forbidden",
  "errorStatus": 403,
  "message": "Rumble requires you to sign in to view this video's comments"
}

Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Rumble video URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only mark readOnlyHint=false/openWorld/idempotent=false, but the description adds the real behavioral payload: credit consumption, the confirm=true gate, a 403 'forbidden' outcome that charges no credits, and that read-like POSTs do not publish to social platforms. This is exactly the extra context annotations cannot convey.

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-loads what it does, then return fields, then error semantics, then the illustrative 403 JSON, then the credit/confirm note. Every block earns its place, though the inline JSON example is slightly heavy for the amount of new information it carries.

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?

There is no output schema, so the description correctly enumerates the returned fields (comment text, author, createdAt, createdAtText, likeCount, dislikeCount, replyCount) and documents both success and failure shapes. An agent has everything needed to call it and interpret results.

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 reinforces the meaning of confirm (credit-consuming approved call) and ties url to a Rumble video URL. It adds modest interpretive value over the schema's own descriptions.

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, resource, and scope: 'Gets all top level comments for a Rumble video by URL.' The Rumble platform qualifier separates it cleanly from the many sibling comment tools (youtube_comments, instagram_comments, tiktok_comments, facebook_comments) and from rumble_video/rumble_transcript.

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 clear operating context: it requires confirm=true, may consume paid credits, and distinguishes the sign-in-required 403 case from a genuinely empty comment set. It stops short of explicitly naming alternatives or when-not-to-use conditions, so it is strong context rather than full routing guidance.

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

rumble_searchSearchA

Searches Rumble videos by keyword. Returns matching videos and shorts with title, URL, thumbnail, channel, published date, viewCountText, viewCountInt, and a numeric cursor for the next page. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query.
`cursor`	No	Cursor from the previous response. This is the next page number, like 2 or 3.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Beyond the annotations, the description discloses that the call may consume paid API credits, that confirm=true is required, and that despite being a POST it does not publish to social platforms. That is substantive, non-obvious behavioral context. It stops short of describing rate limits or exactly when credits are charged.

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?

Three tight sentences, front-loaded with purpose, then return fields, then the credit/confirm caveat. Every sentence carries information, though the field enumeration is slightly list-heavy.

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?

There is no output schema, yet the description enumerates the returned fields (title, URL, thumbnail, channel, dates, view counts, cursor), which compensates well. Combined with the credit/confirm disclosure, an agent has enough to call it correctly; only explicit sibling routing is missing.

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 100%, so all four parameters (query, cursor, account, confirm) are already documented in the schema. The description restates the cursor's role as a paging token but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate.

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 ('Searches Rumble videos by keyword') and distinguishes itself from platform siblings like rumble_video, rumble_channel_videos, and rumble_transcript by scoping to keyword search. An agent can identify the right tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Keyword-search semantics imply when to use it versus browsing a channel, but the description never explicitly names an alternative or an exclusion (e.g. use rumble_channel_videos to browse a channel). Usage is implied rather than stated.

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

rumble_transcriptTranscriptA

Gets a Rumble video's transcript when captions are available. If Rumble does not expose captions for the video, transcript will be null and you will not be charged. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Rumble video URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses the paid-credit cost, the confirm=true prerequisite, the null-on-missing-captions outcome, and clarifies that these read-like POSTs do not publish to social platforms — which helpfully reconciles the readOnlyHint=false annotation.

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?

Three tight, front-loaded sentences that each carry distinct information (purpose, null behavior, cost/confirm). No filler, though the credit/publish caveats could be slightly compressed.

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 3-parameter tool with no output schema and full schema coverage, the description is nearly complete — it covers the failure mode (null), cost, and confirmation. Minor gaps remain around account selection behavior, but nothing essential is missing.

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 100%, so the schema already documents url, account, and confirm. The description adds only the confirm=true requirement, which is already stated in the schema, so baseline 3 is appropriate.

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 — 'Gets a Rumble video's transcript' — and scopes it to Rumble, clearly distinguishing it from siblings like rumble_video, rumble_comments, and transcript tools on other platforms.

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 clear context for use: it returns a transcript when captions exist, returns null otherwise, and requires confirm=true. It stops short of naming an alternative or an explicit when-not-to-use-this-vs-sibling condition, so it lacks the routing language of a 5.

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

rumble_videoVideoA

Gets Rumble video details by URL. Returns title, description, thumbnail, channel, publish date, view count, likes, dislikes, captions, and media metadata when available. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Rumble video URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Adds real value beyond the annotations: it discloses that the call may consume paid credits, mandates confirm=true, and explains that the read-like POST does not publish to social platforms, which reconciles the non-readOnlyHint. It stops short of describing pagination or rate-limit behavior.

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?

Three tight sentences with the core purpose front-loaded, followed by returns and then operational caveats. Efficient, though the returns enumeration is somewhat long for a no-output-schema tool.

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?

With no output schema, the description compensates by listing the returned fields, and it covers the billing/confirm caveat. For a single-URL lookup this is nearly complete; only pagination or failure behavior is unaddressed.

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 coverage is 100%, so the schema already documents url, account, and confirm. The description reinforces that the input is a URL and that confirm gates the credit-consuming call, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 ('Gets Rumble video details by URL') and enumerates the returned fields. An agent can distinguish it from rumble_search, rumble_channel_videos, and rumble_transcript without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'by URL' phrasing implies when this applies, and it notes confirm=true is needed for the credit-consuming call. However, it never routes the agent to alternatives such as rumble_transcript for captions or rumble_channel_videos for listings, leaving the choice to inference.

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

scrapecreators_get_credit_balanceGet credit balanceB

Read-onlyIdempotent

Returns the number of API credits remaining on your Scrape Creators account. The response contains a single creditCount field with your current balance. Account metadata read.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds that the response contains a single creditCount field, which is useful return-value context, but it omits auth/rate-limit or account-selection behavior. This is adequate but not rich.

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?

Two sentences front-load the purpose and return detail efficiently. The trailing 'Account metadata read' is mildly redundant but does not bloat the 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 simple read tool with rich annotations and full schema coverage, the description is nearly sufficient: it states what is returned via the creditCount field. It does not fully explain the optional account parameter or output format, but no output schema exists and the missing details are minor for invocation.

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?

There is one optional parameter with 100% schema description coverage, so the schema already documents that 'account' selects credentials rather than a remote account ID. The description adds no additional parameter meaning beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Returns' and resource 'API credits remaining' with clear scope. It does not explicitly distinguish from sibling account tools like get_daily_usage or get_request_history, but the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, prerequisites, or alternatives are provided. The phrase 'Account metadata read' is a tagline rather than guidance; an agent must infer that this is for checking balance.

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

scrapecreators_get_daily_usageGet daily usageB

Read-onlyIdempotent

Returns aggregated daily usage statistics for the last 30 days, including total credits consumed and number of requests per day. Account metadata read.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful fixed 30-day window and the exact metrics returned, but says nothing about pagination, result size, rate limits, or auth requirements.

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 core purpose and confined to two short sentences with no filler. The final fragment "Account metadata read." is slightly cryptic but functionally a categorization tag.

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 no-argument read-only aggregate tool, stating the window and the returned metrics covers what an agent needs; no output schema exists but the return contents are summarized. Missing only retrieval-edge behavior such as pagination or empty-window handling.

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?

Only one optional parameter and schema coverage is 100%, so the schema already carries the semantics, including the important note that "account" selects local credentials rather than a remote ID. The description adds no parameter meaning, which is acceptable at this coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Returns") and resource ("aggregated daily usage statistics") with concrete scope: last 30 days, credits consumed, requests per day. The detail implicitly separates it from scrapecreators_get_credit_balance and scrapecreators_get_request_history, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use, when-not-to-use, or alternative-routing guidance. The trailing tag "Account metadata read." is a category label, not usage direction, and the many account/tiktok/instagram siblings are left unaddressed.

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

scrapecreators_get_most_used_routesGet most used routesA

Read-onlyIdempotent

Returns your top 20 most called API endpoints ranked by call count, along with total credits consumed per endpoint. Defaults to the last 24 hours. Supports custom time ranges up to 1 year. Account metadata read.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`end_time`	No	End of time range (ISO 8601 format)
`start_time`	No	Start of time range (ISO 8601 format)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the bar is lower. The description still adds real value: a hard cap of 20 results, ranking by call count, per-endpoint credit consumption, the default 24-hour window, and the 1-year range ceiling. The trailing 'Account metadata read.' hints at the credential/account scope.

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 core capability and tightly written across three short sentences with no filler. The trailing fragment 'Account metadata read.' is slightly cryptic and could have been folded into the main sentences, but overall it is efficient.

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?

With no output schema, the description carries the burden of describing the return value and does so well: the top 20 endpoints, call counts, and credits consumed. Combined with full schema coverage and read-only annotations, an agent has nearly everything needed to call it correctly, with only sibling routing left implicit.

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 coverage is 100%, so the schema already documents account, start_time and end_time, making 3 the baseline. The description reinforces the time-range semantics (default 24h, max 1 year) but adds nothing about the account parameter or ISO 8601 formatting beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: 'Returns your top 20 most called API endpoints ranked by call count, along with total credits consumed per endpoint.' It is unambiguous what the tool does, though it never names or contrasts the closely related siblings (scrapecreators_get_daily_usage, scrapecreators_get_request_history), so the agent must infer differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the default window (last 24 hours) and the maximum supported range (up to 1 year), which is useful operating context. However, there is no explicit when-to-use guidance or comparison against the overlapping usage/history siblings, so the choice between them is left to inference.

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

scrapecreators_get_request_historyGet request historyA

Read-onlyIdempotent

Returns a paginated list of your API requests, including the endpoint called, status code, credits used, and timestamp. Useful for debugging and monitoring your API usage. Supports filtering by endpoint name and status code. Account metadata read.

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number for pagination (max 100)
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`endpoint`	No	Filter by endpoint name (partial match)
`statusCode`	No	Filter by HTTP status code

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the return shape (a paginated list with endpoint, status, credits, timestamp) which matters since there is no output schema, but it says nothing about pagination limits, auth requirements, or retention window.

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?

Four short sentences, front-loaded with what is returned before the use case and filters, with essentially no padding. The trailing fragment 'Account metadata read.' is a slightly odd category tag but not wasteful.

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 four-parameter read/list tool with no output schema, the description covers the return fields, filters, and purpose adequately, and annotations carry the safety profile. Minor gaps remain around pagination limits and the account-selector parameter, but nothing blocks correct invocation.

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 coverage is 100%, so all four parameters are already documented in the schema. The description echoes the two filter params (endpoint name, status code) and 'paginated' implies the page param, but adds no syntax, format, or defaulting detail beyond the schema, and never mentions the account selector. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Returns a paginated list of your API requests') and enumerates the returned fields (endpoint, status code, credits used, timestamp), so the agent knows exactly what it retrieves. It does not explicitly differentiate itself from close siblings like scrapecreators_get_daily_usage or scrapecreators_get_most_used_routes, which also expose account/usage data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It offers a purpose context ('useful for debugging and monitoring your API usage') which implies when to reach for it, but never states when to prefer it over the usage/route/credit sibling tools nor any exclusions. The usage signal is implied rather than explicit.

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

snapchat_spotlight_by_linkSpotlight by LinkA

Fetches public data for a Snapchat Spotlight video by URL. Returns the snap id, description, creator, engagement counts, thumbnail, and content URL when Snapchat exposes them publicly. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Snapchat Spotlight URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds real value by explaining the apparent read/write ambiguity ('Read-like POST requests do not publish to social platforms') and by disclosing credit consumption plus the confirm gate. It stops short of describing rate limits or failure modes, so not 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, tightly front-loaded: the purpose comes first, followed by the output fields and the operational caveats. No filler or repetition, and every clause carries information an agent needs.

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 single-resource fetch with no output schema, the description usefully summarizes the return shape and covers the credit/confirm behavior. It is nearly complete; the only minor gap is that it never differentiates the Snapchat Spotlight siblings, which would help an agent choose correctly.

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 100%, so the schema already documents url, account, and confirm, establishing the baseline of 3. The description reinforces the confirm requirement and the URL-based input but adds no syntax or format detail (e.g., expected URL shape) beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Fetches public data for a Snapchat Spotlight video by URL,' and even enumerates the returned fields (snap id, description, creator, engagement, thumbnail, content URL). This clearly separates it from snapchat_user_profile, though it does not explicitly name that sibling or snapchat_spotlight_comments_by_link to reinforce the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies a prerequisite ('requires confirm=true') and a cost warning about paid API credits, which are useful invocation conditions. However, it gives no explicit when-to-use guidance against the sibling Snapchat tools (e.g., profile vs. comments by link), leaving routing to inference from the name.

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

snapchat_spotlight_comments_by_linkSpotlight Comments by LinkA

Fetches public comments from Snapchat's Spotlight comments API by URL. Returns the snap id, comments, a cursor for the next page, and hasMore. Pass the returned cursor back as the cursor param to load more comments. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Snapchat Spotlight URL.
`cursor`	No	Pagination cursor from the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, and the description usefully explains the apparent read/write tension: it is a 'read-like POST' that does not publish, while flagging credit consumption and the required confirm=true. This adds real context beyond the structured hints, though it does not cover rate limits or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, followed by return shape, pagination usage, and the credit/confirm caveat. Every sentence earns its place with no redundancy.

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?

With no output schema, the description carries the return-value burden well, listing snap id, comments, cursor, and hasMore. Combined with the credit/confirm disclosure and pagination loop, an agent has everything needed to invoke it correctly.

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 adds meaning beyond the schema by explaining the cursor round-trip ('Pass the returned cursor back as the cursor param to load more comments'), which documents the pagination workflow that the schema field alone does not convey. The account and confirm params are only lightly supported.

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 ('Fetches') and resource ('public comments from Snapchat's Spotlight comments API by URL'), which cleanly distinguishes it from the sibling snapchat_spotlight_by_link that fetches the snap itself. An agent can identify the tool's scope without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear pagination usage ('Pass the returned cursor back ... to load more comments') and a prerequisite (confirm=true), but does not explicitly frame when to choose this tool over related siblings such as snapchat_spotlight_by_link or the various *_comments tools. Usage is implied rather than routed.

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

snapchat_user_profileUser ProfileA

Retrieves a Snapchat user's public profile by handle, including identity, stories, and spotlight content. Returns userProfile with username, title, snapcodeImageUrl, subscriberCount, bio, and profilePictureUrl. Also includes highlightStoryMetadata with individual story snaps (mediaUrl, mediaType, thumbnailUrl) and spotlightStoryMetadata with video details and engagement stats (viewCount, shareCount, commentCount). Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Snapchat username
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description usefully reconciles the apparent write-like POST with 'read-like POST requests do not publish to social platforms,' and adds the cost/auth gates (paid credits, confirm=true). It stops short of quantifying credit cost or describing failure behavior (e.g., unknown handle), so it is strong but not exhaustive.

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 core action in the first sentence, then the return payload, then the cost/auth caveats. The dense enumeration of return fields is long but justified because no output schema exists; no sentence is purely redundant.

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?

With no output schema, the description takes on the burden of describing the return shape and does so thoroughly (userProfile fields, highlightStoryMetadata, spotlightStoryMetadata with engagement stats), and it covers the confirm/credit prerequisite. Minor gaps remain around rate limits and error cases, but nothing essential to correct invocation is missing.

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 100%, so handle, account, and confirm are already documented in the schema. The description only restates 'by handle' and the credit/confirm requirement, adding no syntax or format detail beyond the structured fields — baseline 3 applies.

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 ('Retrieves a Snapchat user's public profile by handle') and enumerates the exact scope: identity, stories, and spotlight content. The 'by handle' qualifier also distinguishes it from the sibling tools snapchat_spotlight_by_link and snapchat_spotlight_comments_by_link, which take URLs instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description supplies operational prerequisites ('requires confirm=true', credit consumption) and the handle-vs-link distinction is implied by the name, but it never explicitly says when to prefer this tool over snapchat_spotlight_by_link or the other Snapchat siblings. Usage guidance is implied rather than stated.

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

soundcloud_artistArtistA

Fetches detailed information about a SoundCloud artist by its handle or URL. Returns artist metadata including id, name, followers, etc Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	SoundCloud artist URL. If you'd prefer to use the handle instead, you can use the handle parameter instead.
`handle`	No	SoundCloud artist handle. If you'd prefer to use the URL instead, you can use the url parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Adds context annotations do not carry: it warns about paid API credit consumption, states the confirm=true gate, and preempts the surprising readOnlyHint=false by clarifying that the read-like POST does not publish to social platforms. It does not matter that annotations mark it non-read-only; the description explains the nuance rather than contradicting it.

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-loads the primary action and scope in the first sentence, then appends cost and no-publish caveats. Efficient overall, though the trailing 'etc' and multi-clause final sentence are slightly loose.

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 4-parameter read tool with full schema coverage, it covers purpose, identification inputs, credit cost, and the confirm gate, and hints at the returned fields (id, name, followers). With no output schema, a fuller description of the return shape would help, but nothing essential for a correct call is missing.

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 100%, so url, handle, account and confirm are already documented in the schema. The description merely restates the handle-or-URL choice and the confirm requirement without adding format or syntax detail, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (detailed information about a SoundCloud artist) plus the two ways to identify it (handle or URL). It implicitly distinguishes itself from soundcloud_artist_tracks and soundcloud_track by promising artist metadata rather than tracks, but never explicitly names or differentiates from those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a usage prerequisite (requires confirm=true for the credit-consuming call), which is real when-to-use guidance. However, it names no alternatives and gives no conditions selecting this tool over soundcloud_artist_tracks, soundcloud_track, or a generic search, so the routing guidance is only implied.

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

soundcloud_artist_tracksArtist TracksA

Fetches tracks/songs for a SoundCloud artist by handle or URL. Returns the artist profile, track list, and pagination info from SoundCloud. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	SoundCloud artist tracks URL. If you'd prefer to use the handle instead, you can use the handle parameter instead.
`cursor`	No	Cursor to get more tracks. Get 'cursor' from previous response.
`handle`	No	SoundCloud artist handle. If you'd prefer to use the URL instead, you can use the url parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations set readOnlyHint=false, which on its own could wrongly suggest a mutating operation; the description proactively reconciles this by explaining that read-like POST requests do not publish to social platforms. It also discloses the credit cost and the confirm=true requirement, which annotations do not cover.

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?

Three short sentences, front-loaded with what the tool returns before the cost/prerequisite caveats. No filler, though the trailing clause about POST requests is slightly awkward in placement.

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?

With no output schema, the description usefully names the return payload (artist profile, track list, pagination info). Combined with the credit/confirm disclosure, an agent has enough to call it correctly and interpret the result.

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 100%, so all five parameters are already documented, including the url/handle alternates and the confirm requirement. The description restates handle/URL usage without adding format or constraint detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (tracks/songs for a SoundCloud artist) plus the accepted identifiers (handle or URL). It is distinguishable from soundcloud_artist and soundcloud_track by implication, but no sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It conveys operational prerequisites (requires confirm=true, consumes paid credits) which helps decide whether to invoke it. However it gives no explicit when-to-use / when-not-to-use guidance relative to soundcloud_artist (profile only) or soundcloud_track (single track), leaving the routing inference to the agent.

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

soundcloud_trackTrackA

Fetches detailed information about a SoundCloud track/song by URL. Returns track title, plays, likes, reposts, comments, artwork, artist, and other SoundCloud metadata. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	SoundCloud track URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.5/5.0

Behavior4/5

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

With annotations marking readOnlyHint=false and idempotentHint=false, the description adds genuinely useful context the annotations don't: it consumes paid API credits, requires confirm=true, and explains that this read-like POST does not publish to social platforms. That resolves the ambiguity of a non-readOnly annotation on a fetch tool. It stops short of stating rate limits or credit amounts.

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?

Three tight sentences with the core purpose front-loaded and the credit/confirm caveat immediately after. No filler, though the return-field enumeration is slightly listy.

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?

No output schema exists, so the description compensates by naming the returned fields (title, plays, likes, reposts, comments, artwork, artist). Annotations cover safety and the description covers credits and confirm, leaving only rate-limit/credit-cost specifics unstated.

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 coverage is 100%, so url, account, and confirm are already documented in the schema. The description restates the confirm requirement but adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb+resource ('Fetches detailed information about a SoundCloud track/song by URL') and enumerates the returned fields. It does distinguish the track entity implicitly from soundcloud_artist, but never explicitly names the sibling it is not, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no conditions selecting this over soundcloud_artist_tracks or spotify_track. The only conditional statement is the confirm=true requirement, which is a parameter constraint rather than usage routing.

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

spotify_albumAlbumA

Retrieves detailed information about a Spotify album by its id or URL, including album metadata, artists, release date, cover art, copyright info, tracks, and sharing details. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify album id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify album URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Adds real value beyond the annotations by disclosing that the call may consume paid credits, that confirm=true is mandatory, and that the read-like POST does not publish to social platforms — important context given readOnlyHint=false. It stops short of noting rate limits or failure/error behavior.

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?

Two sentences, front-loaded with purpose followed by caveats. Efficient, though the long enumeration of return fields ('sharing details') is slightly padded.

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?

With no output schema, the description responsibly lists the returned fields and covers cost/confirmation caveats. The remaining gap is that it never routes the agent to alternatives such as spotify_search.

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 coverage is 100%, so the schema already documents id, url, account, and confirm. The description only echoes the id/URL interchangeability and the confirm requirement, adding no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb (retrieves) and resource (Spotify album) and enumerates the payload contents — metadata, artists, release date, cover art, copyright, tracks, sharing. It is clearly distinguishable from siblings like spotify_track or apple_music_album by the resource itself, though it never explicitly contrasts with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives cost/auth context (paid credits, confirm=true) but no when-to-use guidance: nothing tells the agent when to prefer the id vs url parameter, or when to reach for spotify_search first. Usage is implied by the resource name rather than stated.

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

spotify_artistArtistA

Retrieves detailed information about a Spotify artist by their handle, including name, followers count, genres, and related artists. Accepts a handle as input and returns artist metadata such as id, name, followers, genres, and related artists. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify artist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify artist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.6/5.0

Behavior4/5

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

Given annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, the description adds real value by disclosing that the call consumes paid credits, requires confirm=true, and that the read-like POST does not publish to social platforms. That reconciles the non-read-only hint with the tool's actual side effect (credit consumption, not state mutation).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the same return fields (id, name, followers, genres, related artists) are listed twice in consecutive sentences, and the credit/confirm note is bundled into the same paragraph. Trimming the redundant second sentence would tighten it without losing information.

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?

With no output schema and no required parameters, the description sensibly enumerates the returned fields and covers the cost/confirm prerequisite, so an agent has what it needs to invoke the tool. Completion would benefit from clarifying id-vs-url precedence and the confirm gate's relationship to the individual call.

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 100%, so all four parameters (id, url, account, confirm) are already documented in the schema; the description adds no syntax or selection detail beyond it. Its reference to a 'handle' input does not map to any actual parameter, so it slightly muddies rather than enriches parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (retrieves) and resource (Spotify artist metadata) and enumerates the returned fields, which cleanly separates it from siblings like spotify_track or apple_music_artist. However, it says it looks up artists 'by their handle', yet the schema exposes only id and url, never a handle, which introduces a small mismatch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description flags the credit cost and the confirm=true prerequisite, which implies when the call is appropriate, but it never names alternatives such as spotify_search or explains when an agent should prefer this over another lookup route. Usage is implied by the cost warning rather than an explicit when/when-not statement.

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

spotify_playlistPlaylistA

Retrieves public Spotify playlist metadata and up to 50 tracks by playlist id or URL. For playlists with more tracks, pass the returned cursor into the next request until cursor is null. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify playlist id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify playlist URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`cursor`	No	Cursor returned by the previous response. Omit it for the first page.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.4/5.0

Behavior4/5

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

Adds real context beyond the annotations: credit consumption, the confirm=true prerequisite, the pagination termination condition, and a clarification that a read-like POST does not publish to social platforms. This usefully explains why readOnlyHint=false despite non-destructive read semantics, though auth/token requirements and rate limits are not covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences: capability/scope first, then pagination and cost/confirm constraints. No filler, and every clause carries actionable information.

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?

With no output schema, the description still discloses the payload shape (metadata plus up to 50 tracks), the pagination contract, and the credit/confirm gating. Missing only minor details such as behavior on private or unavailable playlists.

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 adds meaning to cursor (iterate with the returned value until it is null) that goes beyond the schema's 'omit for first page' note. The confirm and account parameters are left to their schema descriptions.

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 (retrieves) and resource (public Spotify playlist metadata + up to 50 tracks) with an explicit input mode (id or URL). It is clearly distinguishable from siblings such as spotify_track, spotify_album, spotify_artist, and spotify_search.

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?

Explains the repeated-call pattern precisely: pass the returned cursor until cursor is null, and states the id/URL entry options. It does not name when to prefer this over spotify_search or other Spotify siblings, so no exclusions or alternatives are given.

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

spotify_podcastPodcastA

Retrieves detailed information about a Spotify podcast by its id or URL. Spotify calls podcasts shows internally, so Spotify podcast URLs use /show/. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify podcast id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify podcast URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare openWorldHint, non-idempotent, non-destructive, and non-read-only behavior, so the bar for additional disclosure is lower. The description adds important context beyond annotations: it may consume paid API credits, requires confirm=true, and explains that read-like POST requests do not publish to social platforms. It does not cover auth or rate-limit details, but the credit and confirmation warnings are strong behavioral disclosures.

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?

The description is front-loaded with the primary purpose, followed by a useful naming/URL clarification and critical credit/confirmation requirements. Three sentences, no obvious filler. The final sentence about read-like POST behavior is slightly tangential but still earns its place by addressing a potential agent concern.

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?

Given no output schema, the description could have described the return shape, but it is otherwise complete for a detail-retrieval tool. It covers purpose, resource naming, input alternatives, credit cost, and the confirm requirement. Annotations handle the safety profile, so the description is sufficiently complete for correct invocation.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by clarifying that Spotify podcast URLs use /show/, which helps an agent construct or validate the url parameter. It does not describe the account or confirm parameters beyond what the schema already says, but the URL-format insight is a useful addition.

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: retrieves detailed information about a Spotify podcast by id or URL. The note that Spotify calls podcasts 'shows' internally and uses /show/ URLs further disambiguates the resource. The agent can tell this is a detail-lookup tool rather than a search or episode-list tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a podcast id or URL, but it does not explicitly say when to use this tool instead of siblings such as spotify_search or spotify_podcast_episodes. It also does not state when not to use it. The id/URL alternative is helpful but does not constitute full usage guidance.

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

spotify_podcast_episodesPodcast EpisodesA

Returns episodes for a Spotify podcast. Pass the cursor returned by a response to get the next page. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify podcast id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify podcast URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`cursor`	No	Cursor returned by the previous response. Omit for the first page.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Goes meaningfully beyond the annotations by disclosing that the call may consume paid API credits, that confirm=true is required, and that the read-like POST does not publish to social platforms. These are exactly the behavioral traits annotations cannot express (annotations only say readOnly=false, destructive=false, openWorld=true). It could still say more about pagination termination or failure modes, but this is solid added context.

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?

Three short sentences, front-loaded with the core purpose and then pagination and cost/confirm constraints. No wasted filler, though the final sentence about social publishing is slightly tangential to episode listing.

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 5-param, no-required, no-output-schema tool, the description covers purpose, paging, credit cost, and the confirm gate — the essentials an agent needs to invoke it safely. Missing only explicit sink/alternative routing among the spotify siblings.

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 100%, so id/url/cursor/account/confirm are all documented in structured fields; baseline 3 applies. The description reinforces cursor paging use but adds no format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns episodes for a Spotify podcast.' This clearly distinguishes the episode-listing tool from the sibling spotify_podcast, which presumably surfaces podcast metadata. It stops short of explicitly naming that sibling or its boundary, so it is clear but not maximally differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful invocation context (omit cursor for the first page, pass confirm=true for the approved call), but never states when to choose this tool over spotify_podcast or spotify_search. Usage is implied by the resource description rather than laid out as explicit when/when-not guidance.

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

spotify_searchSearchA

Search Spotify for tracks, artists, albums, episodes, podcasts, and audiobooks. Use type=podcasts when you need podcast ids for the podcast endpoints. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.6/5.0

Behavior4/5

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

Adds valuable context beyond annotations: it warns about paid API credit consumption and the confirm=true requirement, and clarifies that despite being a POST, it does not publish to social platforms. This helps reconcile the readOnlyHint=false annotation without contradicting it.

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 purpose followed by usage hint and behavioral warnings. Four short sentences with little waste, though the 'type=podcasts' sentence could be seen as non-earning if it references a non-existent parameter.

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?

Given no output schema and 100% schema coverage, the description covers purpose, credit cost, confirm requirement, and non-publishing behavior. However, the phantom 'type' parameter is a gap, and the account parameter's role is not elaborated beyond the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description references 'type=podcasts' even though no 'type' parameter exists in the schema. This phantom parameter is misleading and likely to confuse an agent trying to invoke the tool correctly. Other parameters are only restated or left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (Spotify for tracks, artists, albums, episodes, podcasts, audiobooks). This clearly distinguishes it from detail-oriented siblings like spotify_artist or spotify_track, though it does not explicitly name alternatives. The 'type=podcasts' hint references a parameter not in the schema, adding slight confusion.

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 an explicit use case: 'Use type=podcasts when you need podcast ids for the podcast endpoints.' It also states a key requirement: 'requires confirm=true' for credit-consuming calls. No when-not guidance or named alternative tools, but the context is clear.

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

spotify_trackTrackA

Retrieves detailed information about a Spotify track by its id or URL, including track metadata, artists, album info, duration, playability, and sharing details. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`id`	No	Spotify track id. If you'd prefer to use the URL instead, you can use the url parameter instead.
`url`	No	Spotify song URL. If you'd prefer to use the id instead, you can use the id parameter instead.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

With annotations present the bar is lower, and the description adds genuinely useful context the annotations cannot: paid API credit consumption, the confirm=true gate, and the clarification that this is a read-like POST that does not publish to social platforms. That last sentence usefully explains why readOnlyHint=false even though the operation is a retrieval, though it stops short of describing rate limits or failure modes.

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?

Two sentences, front-loaded with purpose and followed by cost/confirmation caveats; nothing is padding. The second sentence is dense but each clause (credits, confirm flag, no social publishing) carries distinct information the agent needs.

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?

There is no output schema, so the description correctly compensates by naming the returned fields, and it covers cost and confirmation preconditions. What remains thin is discovery guidance (how to obtain an id) and any notion of error or empty-result behavior, which are minor for a single-resource lookup.

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 100% and each parameter (id, url, account, confirm) is already documented in the schema, so the baseline is 3. The description reiterates the id-or-URL duality and the confirm requirement, adding no syntax, format, or constraint detail beyond what the schema already states.

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 ('Retrieves') and a specific resource ('a Spotify track by its id or URL'), then enumerates the returned payload (metadata, artists, album info, duration, playability, sharing details). This clearly separates it from sibling lookups like spotify_artist, spotify_album, spotify_playlist and apple_music_track/soundcloud_track without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one concrete precondition ('requires confirm=true') and warns about credit consumption, which is real usage guidance. However, it never says when to reach for this tool versus spotify_search (to discover an id) or spotify_album/spotify_artist for adjacent resources, leaving the routing decision to inference.

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

telegram_channel_detailsChannel DetailsA

Retrieves public Telegram channel or group metadata including its name, description, avatar, verification status, subscriber or member count, and public media counters. This endpoint uses Telegram's public web preview and does not use a logged-in Telegram account. Private channels, invite-only groups, numeric IDs, and channels with no public web preview are not supported. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Public Telegram handle, @handle, or t.me channel URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior4/5

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

Annotations are thin (readOnly=false, openWorld=true, idempotent=false, destructive=false), so the description carries real weight: it discloses the public-web-preview mechanism, that no logged-in account is used, that it consumes paid credits and requires confirm=true, and that the read-like POST does not publish anywhere. It notably pre-explains why a read operation carries readOnlyHint=false.

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?

Three front-loaded sentences: purpose, mechanism, limitations, then cost/safety. Efficient with little waste, though the trailing 'Read-like POST requests do not publish to social platforms' is slightly boilerplate.

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?

With no output schema and full schema coverage, the description supplies the mechanistic context (public preview, no login), the cost/confirm gate, and the unsupported-input list. Complete enough to invoke correctly; only the absence of alternative routing leaves a small gap.

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 100%, so the schema already documents handle, account, confirm, and cache_max_age. The description reinforces the confirm=true and credit-cost behavior but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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 (retrieves public Telegram channel/group metadata) and enumerates exactly what's returned: name, description, avatar, verification status, subscriber/member count, media counters. This clearly distinguishes it from siblings like telegram_channel_posts and telegram_post_details.

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?

Explicitly states the exclusions — private channels, invite-only groups, numeric IDs, and channels lacking a public web preview are unsupported — which tells the agent when this tool will fail. It does not, however, name a sibling alternative to use in those cases, so it stops short of full when/when-not routing.

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

telegram_channel_postsChannel PostsA

Retrieves one public web-preview page of Telegram posts with text, publish date, views, reactions when exposed, forwards, media previews, and link previews. Pass the returned cursor to fetch the previous page. Empty and terminal pages are not charged. Telegram does not expose every field on every public post, so reactions and downloadable media URLs can be absent. This endpoint does not support private or invite-only channels and groups. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	Numeric cursor returned by the previous page. Omit it for the latest posts.
`handle`	Yes	Public Telegram handle, @handle, or t.me channel URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.3/5.0

Behavior5/5

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

Substantially exceeds the annotations (which only say readOnly=false, openWorld=true, idempotent=false, destructive=false). It discloses credit consumption, the confirm=true requirement, that empty and terminal pages are not charged, that reactions and downloadable media URLs may be absent, and that read-like POSTs do not publish to social platforms.

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?

Two tightly packed paragraphs, front-loaded with what the tool returns before pagination and cost caveats. Nearly every sentence earns its place, though the closing note about not publishing to social platforms is somewhat tangential to retrieval.

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?

With no output schema, the description compensates by enumerating the returned fields, pagination model, cost/pricing behavior, and data-availability caveats. Nothing an agent needs to call this 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 description coverage is 100%, so the schema already documents all five parameters, making 3 the baseline. The description still adds value by explaining cursor pagination direction ('previous page') and the credit/caching consequence of confirm, which the schema strings do not tie together.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves one public web-preview page of Telegram posts') and enumerates the returned fields. It also clarifies scope by excluding private/invite-only channels and groups. However, it never names the adjacent siblings telegram_channel_details or telegram_post_details, so the agent must infer the boundary from scope wording alone.

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 operational guidance: pass the returned cursor to fetch the previous page, omit it for latest posts, and the endpoint is unsupported for private/invite-only channels. Lacks an explicit 'use X instead when you want Y' routing statement against the sibling Telegram tools.

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

telegram_post_detailsPost DetailsA

Retrieves one public Telegram post with its text, publish date, views, reactions when exposed, forward source, media previews, and link preview. This endpoint uses Telegram's public post widget without a logged-in account. Private and invite-only posts are not supported. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Public Telegram post URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.4/5.0

Behavior5/5

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

Annotations set readOnlyHint=false, which would otherwise look like a write operation; the description resolves this by explaining it is a read-like POST that does not publish to social platforms, and adds that it consumes paid API credits and needs confirm=true. This is exactly the extra context the annotations cannot convey.

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?

Two short paragraphs, front-loaded with what the tool returns, followed by access limits and the credit/confirm mechanics. Nearly every sentence earns its place, though the closing sentence is slightly redundant with the caching text already in the schema.

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?

With no output schema, the description compensates by enumerating the returned fields, and it covers access scope, auth/credit requirements, and caching behavior. An agent has everything needed to call this correctly.

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 coverage is 100%, so url, account, confirm, and cache_max_age are already documented in the schema. The description reinforces the confirm=true requirement and the credit/caching behavior, but adds little semantics the schema does not already carry, so the baseline of 3 applies.

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?

The description opens with a specific verb+resource ("Retrieves one public Telegram post") and enumerates exactly what comes back (text, publish date, views, reactions, forward source, media previews, link preview). The word "one" and "public" clearly separate it from sibling listing tools like telegram_channel_posts and telegram_channel_details.

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?

It states a real exclusion (private and invite-only posts are not supported) and a hard precondition (requires confirm=true), plus how caching affects credit spend. It doesn't name an alternative tool for cases where a post is private, but the context needed to decide whether to call it is clear.

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

threads_postPostA

Fetches a single Threads post by URL, returning the post's caption, like_count, view_counts, reshare_count, direct_reply_count, image_versions2, text_post_app_info, and taken_at. Also includes comments, threadItems, and relatedPosts arrays. threadItems contains public continuation posts by the original author and stays separate from comments. Supports a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the post to get
`trim`	No	Set to true for a trimmed down version of the response
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which could mislead an agent into assuming a write; the description usefully resolves this by stating these are 'read-like POST requests [that] do not publish to social platforms', and it adds real operational context: credit consumption and the confirm=true requirement. It stops short of describing failure modes, rate limits, or idempotency behavior, so not 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?

Purpose is front-loaded and the cost/confirm warning is appropriately placed at the end. The long inline enumeration of return fields (like_count, image_versions2, text_post_app_info, etc.) is verbose, though defensible given there is no output schema.

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?

With no output schema, the description carries the return-value burden and does so by listing scalar fields plus the comments/threadItems/relatedPosts arrays, and it clarifies that threadItems (author continuations) differ from comments. Combined with the credit/confirm notes, this is nearly complete; only error and caching tradeoff behavior is left to the schema.

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 100%, so the schema already documents url, trim, account, confirm, and the cache_max_age enum; baseline is 3. The description reinforces trim ('lighter responses') and the credit rationale behind confirm, but adds no syntax or format meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete verb+resource+scope: 'Fetches a single Threads post by URL', which lets an agent distinguish it from list-style siblings like threads_posts. It does not, however, explicitly name an alternative (threads_posts, threads_search_by_keyword) to route between, so it stays below the 'sibling differentiation' bar for a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the required url parameter (single-post retrieval) and by the note that trim yields lighter responses. There is no explicit when-to-use/when-not-to-use guidance or pointer to the sibling that lists a user's posts or searches by keyword, so an agent must infer the boundary between threads_post and threads_posts.

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

threads_postsPostsA

Fetches the most recent posts from a Threads user, returning id, caption text, code, like_count, reshare_count, direct_reply_count, repost_count, image_versions2, video_versions, and taken_at. Only the last 20-30 posts are publicly visible. Supports a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	Yes	Threads username
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

With annotations declaring readOnlyHint=false and idempotentHint=false, the description adds real value beyond them: it warns that the call consumes paid API credits, requires confirm=true, and clarifies that this read-like POST does not publish to social platforms — directly defusing the misleading readOnlyHint=false. This is genuinely helpful behavioral disclosure.

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?

Three dense sentences, front-loaded with purpose and return fields, then constraints. The field enumeration is long but justified given there is no output schema. Little wasted verbiage.

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 tool with no output schema, enumerating the return fields is the right compensating move, and it covers credit cost, the confirm gate, and the 20-30 post visibility ceiling. Only the absence of guidance about sibling alternatives keeps it short of complete.

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 100%, so trim, handle, account, and confirm are all already documented. The description's mention of trim and confirm largely restates the schema; it adds only marginal gloss (trim = lighter response) rather than new meaning. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches), resource (most recent posts from a Threads user), and enumerates the returned fields, so the agent immediately knows what comes back. It does not explicitly distinguish itself from close siblings like threads_profile, threads_post, or threads_search_by_keyword, but the 'user's recent posts' scope is unambiguous on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful operational context (only the last 20-30 posts are public, trim for lighter responses, confirm=true required) but never states when to pick this tool over threads_post or threads_search_by_keyword. Usage is implied rather than directed.

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

threads_profileProfileA

Retrieves a Threads user's public profile including username, full_name, biography, profile_pic_url, follower_count, is_verified, bio_links, and hd_profile_pic_versions. Also indicates whether the account is a threads-only user via is_threads_only_user. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Threads username
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior5/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, which could mislead an agent; the description preempts that by explaining these are read-like POST requests that do not publish to social platforms. It also discloses credit consumption, the confirm=true gate, and cache-vs-live behavior, all beyond what annotations provide.

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?

Two dense sentences: the field list first, then the cost/safety caveats. Nothing is wasted, though the long field enumeration is slightly list-heavy for a 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?

With no output schema, the description usefully enumerates what is returned (username, follower_count, is_verified, bio_links, etc.), and covers the credit/confirm constraints. It stops short of describing error or empty-profile behavior, but is otherwise sufficient for the call.

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 100%, so handle, account, confirm, and cache_max_age are already fully documented in the schema, including the enum and caching semantics. The description adds no parameter-level detail, so the baseline 3 applies.

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+resource ('Retrieves a Threads user's public profile') and enumerates the returned fields, which cleanly distinguishes it from siblings like threads_search_users or threads_posts. An agent knows exactly what this returns without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives preconditions (requires confirm=true, consumes paid credits) but never states when to choose this over alternatives such as threads_search_users, which also take a handle-ish query. Usage is implied through the credit/confirm constraint rather than routed explicitly.

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

threads_search_by_keywordSearch by KeywordA

Searches Threads for posts matching a keyword, returning up to 10 results with caption text, like_count, reshare_count, direct_reply_count, user info, and image_versions2. Supports optional start_date and end_date filters plus a trim option. Only 10 results are returned per request due to public API limitations. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`query`	Yes	Keyword to search for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`end_date`	No	End date to search for
`start_date`	No	Start date to search for

TDQS

A3.9/5.0

Behavior5/5

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

With readOnlyHint=false and idempotentHint=false in the annotations, the description usefully explains the discrepancy: this is a read-like POST that does not publish, but it consumes paid API credits and needs confirm=true, and it caps at 10 results per request due to API limits. These are exactly the behavioral traits an agent cannot infer from the structured fields.

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?

Three sentences, front-loaded with the core action and its result set, then filters, then the credit/limit constraints. No filler, though the credit/limit sentence packs several constraints together.

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 credit-consuming POST with no output schema, the description compensates by listing return fields (caption text, like_count, reshare_count, direct_reply_count, user info, image_versions2), the 10-result cap, and the confirm/credit requirement. Date format expectations for start_date/end_date remain unspecified.

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 100%, so all six parameters are already documented (query, trim, account, confirm, start_date, end_date). The description restates the date and trim filters but adds no syntax, format, or date-format detail, and never mentions the account parameter, so it lands at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Searches Threads for posts matching a keyword') and enumerates the returned fields, which distinguishes it from threads_search_users and threads_posts without needing the schema. It stops short of explicitly naming a sibling, so a 4 rather than a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes optional start_date/end_date and trim filters and the confirm requirement, which implies when the tool is usable, but it never says when to choose this over threads_search_users, threads_posts, or other keyword-search siblings. Usage is implied rather than guided.

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

threads_search_usersSearch UsersA

Searches for Threads users by username, returning matching profiles with username, full_name, profile_pic_url, is_verified, and pk. Useful for finding user accounts before fetching their profile or posts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Username to search for
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations flag readOnlyHint=false but destructiveHint=false; the description reconciles that tension by stating read-like POSTs don't publish to social platforms, and adds two traits not in the annotations: paid credit consumption and the confirm=true gate. Remaining gaps are minor (no rate-limit or pagination detail).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with purpose followed by usage context and then the cost/confirm constraint. With no output schema, the field enumeration earns its place rather than being filler.

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 a 3-param search tool with no output schema, the description covers return shape, intended usage, credit cost, and the confirm flag. Nothing an agent needs to invoke it correctly is missing.

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 100%, so all three parameters (query, account, confirm) are already documented in the schema, including the credential-vs-remote-account nuance of 'account'. The description only restates the confirm requirement without adding format or syntax detail, so the baseline 3 is appropriate.

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 ('Searches for Threads users by username') and enumerates the returned fields, distinguishing it from the domain's keyword search sibling (threads_search_by_keyword). An agent can tell what it does without opening the schema.

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 a clear workflow context ('finding user accounts before fetching their profile or posts'), which tells the agent when this is the right starting point. It stops short of naming the alternative (threads_search_by_keyword) or stating when-not-to-use, so no explicit routing.

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

tiktok_ad_library_ad_library_adAd Library AdA

Fetches one TikTok ad by ID or URL. It first checks Creative Center Top Ads (ads.tiktok.com), then TikTok's public transparency Ads Library (library.tiktok.com) when the ID is not a Top Ads material. Both sources return the same response shape. Fields TikTok does not expose for a public Ads Library ad are null, empty, or false as appropriate. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`ad_id`	Yes	Creative Center Top Ads material ID or URL, or a public Ads Library ad ID or library.tiktok.com detail URL.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond them: paid credit consumption, the confirm=true gate, the Top Ads → Ads Library fallback order, and how unexposed fields are returned (null/empty/false). It also clarifies the POST does not publish, resolving the apparent contradiction with a read-like operation.

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?

Four sentences, front-loaded with the core action and source-resolution behavior; the null-field caveat is useful. Minor redundancy between the first sentence and the schema's ad_id description, but nothing wasteful.

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?

No output schema exists, so the description carries some return-value burden and appropriately explains the shared response shape and null-field behavior. Combined with the confirm/credit warning and source fallback, it is close to complete for a 3-param, single-ad fetch tool.

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 100%, so all three parameters are already documented. The description restates the dual ID/URL acceptance but adds no syntax, format, or edge-case guidance beyond what the schema provides, so it lands at the baseline.

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 (fetches) and resource (one TikTok ad) and clarifies it accepts either an ID or URL. It also distinguishes itself from the sibling tiktok_ad_library_ad_library_search by describing single-ad retrieval and the dual-source resolution order, so an agent can tell them apart 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 Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage (retrieve a single ad when you already have an ID/URL) is clear, and it notes confirm=true is required, but it never explicitly states when to prefer this over the sibling search tool or what inputs select each source.

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

tiktok_ad_library_ad_library_searchAd Library SearchA

Searches TikTok's public Ads Library using either query for a general search or advertiser_name for advertiser-specific results. Advertiser-name searches resolve the name through TikTok's advertiser typeahead first, then search the selected advertiser entity and return adv_biz_ids on each ad. You can pass adv_biz_ids with advertiser_name to pin the exact advertiser shown in TikTok's See all ads link. TikTok requires the name with the ID and ignores an ID-only search, so provide exactly one of query or advertiser_name. If TikTok has no matching advertiser entity, the API falls back to TikTok's name search. Results are global, sorted by the latest shown date, support cursor pagination, and include a public TikTok Ads Library URL for each ad. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	No	General ad search. Provide either query or advertiser_name, not both.
`cursor`	No	Opaque cursor returned from the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`adv_biz_ids`	No	TikTok advertiser business ID from a See all ads link. Use it with advertiser_name to pin the exact advertiser. Required companion: advertiser_name; ID-only searches return 400 because TikTok ignores the ID without the name.
`advertiser_name`	No	Advertiser name to resolve through TikTok's typeahead and search by advertiser entity. Falls back to TikTok's name search when no entity matches. Provide either advertiser_name or query, not both.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds real context beyond them: paid credit consumption, mandatory confirm, ID-only searches returning 400, typeahead resolution, global scope, latest-shown-date sorting, cursor pagination, and per-ad return fields. The 'read-like POST does not publish' note reconciles the read-like behavior with readOnlyHint=false rather than contradicting it.

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?

Dense but front-loaded: the query-vs-advertiser_name distinction leads, with edge cases and the credit/confirm note after. A few clauses (the fallback restated in both description and schema) are slightly redundant, keeping it from a 5.

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?

With no output schema, the description takes on the burden of describing returns (adv_biz_ids per ad, a public Ads Library URL, cursor pagination) and covers the credit/confirm prerequisite. Nothing an agent needs to call this 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 adds cross-parameter meaning the schema does not: the required companionship of adv_biz_ids and advertiser_name, the mutual exclusivity of query and advertiser_name, and the typeahead resolution behavior. It stops short of adding format/syntax hints for cursor or account.

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 ('Searches TikTok's public Ads Library') and immediately distinguishes its two modes, general query vs advertiser_name search. An agent can tell it apart from sibling tiktok_ad_library_ad_library_ad and the Facebook/Google/LinkedIn ad-library searches from the description alone.

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?

Explicitly states how to choose between the two input paths ('provide exactly one of query or advertiser_name'), how to pin an advertiser by pairing adv_biz_ids with advertiser_name, and the fallback when no entity matches. It also discloses the confirm=true requirement and credit consumption, which is genuine selection guidance.

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

tiktok_audience_demographicsUser's Audience DemographicsA

Retrieves audience demographic data for a TikTok user, showing where their followers are located by country. Returns audienceLocations, an array of objects each containing country, countryCode, count, and percentage. Costs 26 credits per request. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	TikTok handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds real value beyond that: a per-request credit cost, the mandatory confirm=true gate, and an explicit clarification that these read-like POSTs do not publish to social platforms, which resolves the tension with readOnlyHint=false.

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 purpose, then return shape, then cost/consent caveat — a logical order with little waste. The final sentence about read-like POST requests is slightly tangential but earns its place by reconciling with readOnlyHint=false.

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?

With no output schema, the description compensates by naming the returned audienceLocations array and its fields (country, countryCode, count, percentage), and it covers the cost and consent constraints. An agent has everything needed to invoke it correctly.

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 100%, so handle, account, and confirm are already documented in the schema; baseline is 3. The description reinforces the confirm requirement and the credit cost but adds no syntax or format detail beyond the structured fields.

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 (retrieves) and resource (audience demographic data / follower locations by country) for a TikTok user, and names the exact fields returned. This clearly separates it from siblings like tiktok_followers or tiktok_profile_region, which return different data shapes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (fetch follower location breakdown for a given handle) and adds a strong pre-condition (confirm=true, 26 credits per request), but never states when to prefer this over alternatives such as tiktok_profile_region or tiktok_followers. No exclusions or routing guidance.

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

tiktok_collection_videosCollection VideosA

Fetches the videos saved in a public TikTok collection, which TikTok also calls a playlist. Pass the collection URL. Returns videos using TikTok's native web video object format, including id, desc, author, stats, and video. To fetch the next page, pass the previous response's max_cursor as cursor when has_more is true. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Public TikTok collection URL
`cursor`	No	Cursor to get more videos. Use max_cursor from the previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior4/5

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

Adds real context beyond the annotations: it warns that the call may consume paid API credits, requires `confirm=true`, and clarifies that read-like POST requests do not publish to social platforms (reconciling with readOnlyHint=false). It does not quantify credit cost or discuss failure modes, but the safety/cost profile is well disclosed.

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-loads what the tool does, then return format, then pagination, then cost/confirm caveats. Dense but every sentence carries useful information; minor verbosity in the credit/confirm sentence.

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?

With no output schema, the description steps in to name the returned fields and explains pagination, which is what an agent needs. It omits error handling and the exact cost of a credit-consuming call, but is otherwise complete for this four-parameter fetcher.

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 parameter documentation largely lives in the schema. The description still adds value by tying `cursor` to the prior response's `max_cursor` and gating it on `has_more`, giving pagination semantics the schema alone only partially conveys.

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 (fetches) and resource (videos saved in a public TikTok collection/playlist), and describes the return shape (`id`, `desc`, `author`, `stats`, `video`). This clearly distinguishes it from siblings like tiktok_profile_videos or tiktok_video_info.

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 explicit operational guidance: pass the collection URL, and paginate by passing the previous response's `max_cursor` as `cursor` when `has_more` is true. It does not explicitly say when to prefer this over sibling tools (e.g., profile videos), but the context is clear enough to invoke correctly.

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

tiktok_comment_repliesComment RepliesA

Fetches replies to a specific TikTok comment by its ID. Returns comments, an array of comment objects each with text, user info, and create_time. Paginate with cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	TikTok video URL. This is the url from the comments endpoint.
`cursor`	No	Cursor to get more replies. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`comment_id`	Yes	TikTok comment ID. This is the cid from the comments endpoint.

TDQS

A3.9/5.0

Behavior4/5

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

Goes well beyond the annotations: discloses that the call may consume paid API credits, requires confirm=true, and explains why a POST is read-like ("do not publish to social platforms"), which resolves the otherwise puzzling readOnlyHint=false. It does not cover auth/account selection or rate limits, so not a full 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?

Four sentences, front-loaded with purpose, then return shape, pagination, and finally the cost/confirm caveat. Dense and mostly waste-free, though the return-shape sentence is somewhat optional given the tool returns objects an agent will inspect anyway.

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 5-param, no-output-schema, credit-consuming POST, the description covers purpose, return fields, pagination, and the cost/confirm gate. Only auth/account-selection behavior and error/rate-limit handling are left to the schema.

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 100%, so the baseline is 3. The description reinforces pagination semantics ("Paginate with cursor from the previous response") and the confirm=true requirement, adding modest value, but otherwise duplicates what the schema already states.

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 (Fetches) and resource (replies to a specific TikTok comment by ID), with the scope narrow enough to separate it from the sibling tiktok_comments (which lists top-level comments on a video) and from youtube/instagram/facebook comment_replies. An agent can tell what it does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by "replies to a specific comment by its ID" and the requirement of a comment_id, but the description never names an alternative or states when-not-to-use (e.g. use tiktok_comments for top-level comments). No explicit routing guidance is given.

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

tiktok_commentsCommentsA

Fetches comments on a TikTok video by URL — useful for reading audience reactions, replies, and engagement. Returns comments, an array where each comment includes text, digg_count (likes), reply_comment_total, create_time, and a user object with the commenter's nickname and unique_id; also returns total comment count. Paginate with cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	TikTok video URL
`trim`	No	Set to true to get a trimmed response
`cursor`	No	Cursor to get more comments. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial behavioral context beyond annotations: it warns of paid credit consumption, mandates confirm=true, and clarifies that the read-like POST does not publish to social platforms — which resolves the apparent tension with readOnlyHint=false. This tells the agent about cost, safety, and side effects directly.

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 core action, then return shape, then pagination and cost. The return-field enumeration is dense but justified given no output schema. Minor verbosity, but every element earns its place.

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?

With no output schema, the description compensates by documenting the returned `comments` array fields, `total`, and pagination. Combined with the credit/confirm safety notes, an agent has everything needed to invoke it correctly.

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 100% schema coverage the baseline is 3, but the description adds practical meaning by explaining that cursor pagination pulls from the previous response and that confirm is required for the credit-consuming call. It does not elaborate on account or trim, keeping it modest above baseline.

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 ('Fetches comments on a TikTok video by URL') and scopes it to a single video, which is distinguishable from siblings like tiktok_comment_replies and tiktok_video_info. An agent can tell what it retrieves without opening the schema.

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?

Frames the use case ('reading audience reactions, replies, and engagement') and explains pagination flows with 'cursor'. It does not explicitly route to a sibling (e.g., tiktok_comment_replies for replies) or state when not to use it, so it stops short of full routing guidance.

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

tiktok_followersFollowersA

Retrieves the follower list of a TikTok account by handle or user_id — useful for seeing who follows a creator or getting subscriber data. Returns followers, an array of user objects each with nickname, unique_id, uid, follower_count, following_count, and avatar URLs; also returns total follower count. Paginate with min_time from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`handle`	No	TikTok handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	User id. Use this for faster response times.
`min_time`	No	Used to paginate. Get 'min_time' from previous response.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=false and openWorldHint=true. The description adds genuinely useful behavior beyond them: it consumes paid API credits, requires confirm=true, is a read-like POST that does not publish to platforms, and documents the pagination contract. It does not explain the readOnlyHint=false annotation directly, but the 'read-like POST' note comes close to reconciling it.

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 core action and return shape, then pagination, then cost gating. Dense but every sentence carries information; the credit/confirm note is worth its space for a paid call.

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?

With no output schema, the description helpfully enumerates the returned `followers` array fields and `total`, and covers pagination and the credit gate. Given 6 optional params and a read-only-ish call, an agent has enough to invoke it correctly; only the sibling routing gap remains.

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 coverage is 100% with 6 documented parameters, so the baseline is 3. The description restates handle/user_id and min_time pagination, and its only marginally additive point (user_id being faster) is already in the schema, so it adds little beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: retrieves the follower list of a TikTok account by handle or user_id, with an explicit use case (seeing who follows a creator, subscriber data). It does not name the obvious sibling tiktok_following (the inverse list), so the agent must infer the distinction rather than being routed explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides real usage context — paginate with `min_time` from the previous response, and confirm=true is required for the credit-consuming call. However, it never says when to prefer this over tiktok_following/tiktok_search_users or when not to use it, so alternative selection is left to inference.

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

tiktok_followingFollowingA

Retrieves the following list — accounts that a TikTok user follows — by their handle. Returns followings, an array of user objects each with nickname, unique_id, uid, follower_count, following_count, signature, and avatar URLs; also returns total count. Paginate with min_time from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`handle`	Yes	TikTok handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`min_time`	No	Used to paginate. Get 'min_time' from previous response.

TDQS

A4.4/5.0

Behavior5/5

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

With readOnlyHint=false potentially confusing an agent, the description resolves the ambiguity by stating these are read-like POST requests that do not publish to social platforms. It also discloses two behaviors annotations do not cover at all: that the call may consume paid API credits and that confirm=true is mandatory.

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 return shape, then pagination, then the credit/confirm caveat — a sensible ordering. The enumeration of seven returned fields is somewhat chatty, but each element is informative given there is no output schema.

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?

With no output schema, the description carries the full burden of the return contract and does so (followings array fields plus total count), alongside pagination guidance and the credit/confirm side-effect notice. Nothing material for a correct invocation is missing.

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 100%, so all five parameters are already documented, including min_time's pagination role and account's credential semantics. The description reinforces min_time pagination but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb+resource (retrieves the following list) and defines the direction explicitly as 'accounts that a TikTok user follows', which cleanly separates it from the sibling tiktok_followers. The lookup key (handle) and the exact shape of the result are stated up front.

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 clear operational context: paginate using min_time from the previous response, and confirm=true is required for the credit-consuming call. It does not explicitly name a competing sibling (e.g. tiktok_followers, tiktok_profile) or state when-not to use it, so it falls short of full alternative routing.

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

tiktok_get_popular_creatorsGet popular creatorsA

Discovers trending and popular TikTok creators, filterable by follower count range, creator country, and audience country. Returns creator_list, an array of creator objects each with nickname, unique_id, follower_count, likes_count, video_views, engagement_rate, and avatar URLs. Sortable by engagement, follower count, or average views. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number
`sortBy`	No	Sort creators by engagement, follower count, or average views
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`followerCount`	No	Filter by follower count range
`creatorCountry`	No	Country code of the creator
`audienceCountry`	No	Country code of the audience/follower

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is partly covered. The description adds genuinely non-redundant behavior: it consumes paid API credits, needs confirm=true, and clarifies that a read-like POST does not publish to social platforms. That is useful cost/side-effect context beyond the annotations.

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-loads what the tool does, then adds cost/confirmation caveats. Two short paragraphs with little waste; the return-field enumeration is slightly listy but justified since there is no output schema.

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?

With no output schema, the description helpfully enumerates the returned creator fields, and it discloses the credit cost and confirm requirement. Pagination behavior via the 'page' parameter is left unexplained, which is the main small gap for a 7-parameter tool.

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 100% and all four enums are documented in the schema, so the baseline is 3. The description restates the filter dimensions (follower range, creator/audience country) and sort keys without adding syntax or semantics the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Discovers trending and popular TikTok creators') plus its filters and sort options. It does not explicitly differentiate itself from nearby siblings like tiktok_search_users or tiktok_profile, but the 'popular/trending discovery' framing is distinctive enough to route an agent reasonably.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete prerequisite (paid credits, requires confirm=true) which is genuine usage guidance, but never says when to prefer this over alternatives such as tiktok_search_users or tiktok_top_search. Usage is implied by the TTL of the tool rather than contrasted with siblings.

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

tiktok_get_song_detailsGet Song DetailsA

Fetches detailed metadata for a specific TikTok sound or song by its clipId. Returns music_info with title, author, album, duration, user_count (number of videos using this sound), play_url, cover art, and artist details. Use the clipId from a sound URL or from the popular songs endpoint. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`clipId`	Yes	This is a little confusing because this isn't songId like you'd think. It is the clipId. I guess because you can clip different portions of a song 🤷‍♂️
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.7/5.0

Behavior5/5

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

Adds traits beyond the annotations: it warns that the call 'potentially consumes paid API credits', requires confirm=true, and clarifies that the read-like POST 'does not publish to social platforms'. This last point usefully explains the otherwise puzzling readOnlyHint=false, reconciling the annotation with the tool's read-like nature rather than contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences with the purpose front-loaded, then return shape, then input sourcing, then cost/side-effect caveats. Every sentence carries distinct information and nothing is redundant.

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?

With no output schema, the description steps in to enumerate the returned music_info fields and their meanings (including user_count). Combined with the credit/confirm caveats, an agent has everything needed to call it correctly.

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 adds real value by explaining the provenance of clipId (sound URL or popular songs endpoint) on top of the schema's own note about the confusing clipId-vs-songId naming. It also reinforces the confirm=true requirement in context.

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 ('Fetches'), a precise resource ('detailed metadata for a specific TikTok sound or song'), and the key it is looked up by (clipId). It is clearly distinguishable from related siblings like tiktok_tiktoks_using_song or tiktok_get_popular_creators without opening any schema.

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?

Tells the agent where the required input comes from ('from a sound URL or from the popular songs endpoint'), which is actionable context. It does not name exclusions or alternatives (e.g., versus the tiktoks_using_song sibling), so it stops short of explicit when-not guidance.

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

tiktok_liveLiveA

Checks if a TikTok user is currently live streaming and retrieves their live room details. Use the top-level is_live boolean instead of checking TikTok's numeric status values yourself. Also returns liveRoomUserInfo (nickname, avatar, followerCount, roomId) and liveRoom (title, startTime, status, liveRoomStats with enterCount and userCount, plus streamData with playback URLs in multiple qualities). Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	TikTok handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Goes beyond the annotations by disclosing that the call 'potentially consumes paid API credits', requires confirm=true, and clarifies that read-like POST requests do not publish to social platforms — meaningful context given readOnlyHint=false and openWorldHint=true could otherwise look risky. It still doesn't say whether the result is cached or how fresh the live status is.

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 core purpose, followed by the behavioral caveats. The long parenthetical enumerating every returned field (nickname, avatar, followerCount, roomId, title, startTime, status...) is somewhat heavy, but it earns place given there is no output schema.

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?

With no output schema, the description usefully enumerates the return payload, and it covers the credit/confirm behavior. The main gap is that it never positions itself against the similarly named tiktok_live_info sibling.

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 100%, so handle, account, and confirm are already documented in the schema; the description adds no further parameter detail. Per the rubric, baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Checks if a TikTok user is currently live streaming and retrieves their live room details.' Clear on its own, but it never distinguishes itself from the sibling tool tiktok_live_info, which by name appears to cover overlapping live-room territory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives usage guidance about the output ('use the top-level is_live boolean instead of checking TikTok's numeric status values yourself'), but that is about interpreting results, not about when to choose this tool versus tiktok_live_info or other live-related siblings. Usage context is implied only.

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

tiktok_live_infoLive InfoA

Gets curated room-level info for a TikTok live using TokAPI's live info endpoint. Use /v1/tiktok/user/live first to find the room_id. If you only have a TikTok handle and need the user's numeric id, use /v1/tiktok/profile first to get user.id. This endpoint is separate from /v1/tiktok/user/live because it uses a different upstream call and returns a smaller response with the most relevant fields: room_id, like_count, viewer_count, status, title, cover_url, and owner. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`room_id`	Yes	TikTok live room id. Get this from `/v1/tiktok/user/live` in `liveRoomUserInfo.roomId` or `liveRoom.id` when the user is live.
`user_id`	Yes	TikTok numeric user id for the live owner. Get this from `/v1/tiktok/profile` in `user.id`.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which could mislead an agent into assuming a mutation; the description resolves this by explaining it is a read-like POST with no publishing to social platforms. It also discloses paid credit consumption and the confirm gate. It does not cover rate limits or failure modes, so not a full 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?

Front-loaded with the core action and sibling differentiation, then prerequisites, then cost warnings. Dense but each sentence carries information; the return-field enumeration slightly bloats an otherwise tight definition.

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?

With no output schema, the description compensates by listing the fields returned, and it fully covers the prerequisite chain, cost model, and confirm requirement. An agent needs nothing else to invoke it correctly.

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 coverage is 100% and each parameter already documents its own origin. The description restates the room_id/user_id provenance paths but adds no syntax, format, or edge-case meaning beyond the schema, so the baseline 3 applies.

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 ('Gets curated room-level info for a TikTok live') and immediately distinguishes itself from the similarly named sibling /v1/tiktok/user/live by naming both the upstream difference and the reduced field set returned.

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 explicit prerequisite ordering: call /v1/tiktok/user/live first for room_id, /v1/tiktok/profile first for user.id, and notes confirm=true is required for the credit-consuming call. This is a full when-and-how recipe rather than an implied context.

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

tiktok_profileProfileA

Fetches public profile data for a TikTok user by their handle or user_id — useful for looking up a creator's identity, bio, and account stats. Returns a user object (display name, avatar URLs, bio/signature, verification status, bio link) and a stats object (followerCount, followingCount, heartCount/total likes, videoCount). This only returns profile metadata, not the user's actual videos or followers list. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	TikTok handle. You can pass handle or user_id.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	TikTok user id.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.1/5.0

Behavior4/5

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

Adds materially beyond the annotations: it discloses paid credit consumption, the confirm=true gate, and reassures that read-like POST requests do not publish to social platforms (which resolves the otherwise confusing readOnlyHint=false). Cache behavior is delegated to the schema's cache_max_age description. It does not discuss rate limits or failure modes, so not 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?

Front-loads purpose, then return shape, then scope exclusion, then cost/safety caveats. The enumeration of user and stats fields is somewhat verbose but justified because no output schema exists. Every sentence carries information; no filler.

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?

With no output schema, the description usefully sketches the return payload and covers the credit/confirm caching constraints an agent must respect. It leaves the handle-vs-user_id selection rule and error/empty-result behavior unspecified, which is a minor gap for a 5-parameter tool.

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 100%, so the schema already documents handle, user_id, account, confirm, and cache_max_age, including the enum and credit implications. The description adds little per-parameter meaning beyond the identity use case, so the baseline 3 applies.

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 (fetch public TikTok profile data by handle or user_id) and enumerates the returned payload (user + stats objects). It explicitly carves out scope boundaries against siblings: 'This only returns profile metadata, not the user's actual videos or followers list,' which separates it from tiktok_profile_videos and tiktok_followers.

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 a clear use case (looking up a creator's identity, bio, account stats) and an implicit exclusion via the scope note about not returning videos or followers, which routes agents to tiktok_profile_videos / tiktok_followers. It stops short of naming those alternatives explicitly or stating prerequisites for choosing between handle and user_id.

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

tiktok_profile_regionProfile RegionA

Returns the TikTok region code for a public profile, like US for United States or MX for Mexico. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	TikTok handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior4/5

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

Annotations already disclose readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description usefully explains that gap by noting these are 'read-like POST requests' that 'do not publish to social platforms,' plus the credit cost. It does not cover rate limits or error behavior, so it stops short of 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences with zero filler: the first gives the purpose and sample output, the second the cost/confirmation constraint and the semantic reassurance about POST usage.

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 single-value lookup with a fully documented schema, the description covers purpose, prerequisites, and the behavioral oddity of a non-read-only POST. It lacks only error/failure behavior, which is a minor gap given no output schema exists.

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 coverage is 100%, so handle, account, and confirm are fully documented in the schema. The description only echoes the confirm=true requirement, adding no syntax or format detail beyond the structured fields. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns the TikTok region code for a public profile') and even illustrates the output format with concrete examples (US, MX). It is clear what the tool does, though it does not name tiktok_profile or any sibling to differentiate itself explicitly.

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 a concrete prerequisite: 'Potentially consumes paid API credits; requires confirm=true.' That tells the agent when this call is appropriate and what gate it must clear, but it offers no alternatives or when-not-to-use guidance relative to the many sibling profile tools.

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

tiktok_profile_videosProfile VideosA

Fetches videos posted by a TikTok user, sortable by latest or most popular — use this to get a creator's video feed or TikToks. Returns aweme_list, an array of video objects each containing aweme_id, desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count, collect_count/saves), and video (download URLs, duration, cover image). Paginate with max_cursor from the previous response. If a profile should have videos but returns none, try region=US or another relevant two-letter country code. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	Yes	TikTok handle
`region`	No	Region (country) for the proxy. Defaults to GB. If a profile should have videos but returns none, try US or another relevant two-letter country code.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	What to sort by
`user_id`	No	TikTok user id. Use this for faster responses.
`max_cursor`	No	Cursor to get more videos. Get 'max_cursor' from previous response.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, which alone is confusing for a POST; the description resolves this by stating it consumes paid API credits, requires confirm=true, and that read-like POSTs do not publish to platforms. That is genuine value beyond the structured hints, though rate-limit or retry behavior is not covered.

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 purpose and sortability, then return shape, then pagination and troubleshooting. Dense and mostly waste-free, though the return-field enumeration (aweme_list, statistics sub-keys) is lengthy for a tool with no output schema and could be trimmed.

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?

With no output schema, the description compensates by naming the top-level return key and key nested fields, and it covers pagination, region fallback, and credit/confirm behavior. Only minor gaps remain, such as how handle vs user_id affect performance beyond the schema note.

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 100%, so handle, region, max_cursor, sort_by, account, confirm, and trim are all documented in the schema itself. The description restates region fallback and cursor pagination but adds no syntax or format detail beyond what the schema already provides; baseline 3 applies.

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 ('Fetches videos posted by a TikTok user') plus the ordering options, which distinguishes it from tiktok_profile (profile metadata), tiktok_video_info (single video), and tiktok_collection_videos (collections) without opening any schema.

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 clear intended use ('get a creator's video feed or TikToks') and concrete operational guidance (paginate with max_cursor, retry with region=US when a profile unexpectedly returns nothing). It stops short of naming which sibling to use instead for adjacent needs, so no explicit exclusions.

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

tiktok_search_by_hashtagSearch by HashtagA

Searches for TikTok videos under a specific hashtag — useful for finding content by topic or trend. Returns aweme_list, an array of video objects each with aweme_id, desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count), video info, and author details. Paginate with cursor from the previous response. TikTok may return duplicate results. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`cursor`	No	Cursor to get more videos. Get 'cursor' from previous response.
`region`	No	Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`hashtag`	Yes	Hashtag to search for (without #)

TDQS

A4.5/5.0

Behavior5/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the description goes well beyond them: it discloses that the call may consume paid API credits, that confirm=true is mandatory, that TikTok may return duplicate results, and clarifies that this read-like POST does not publish to social platforms. That resolves the exact ambiguity the false readOnlyHint creates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first clause, followed by return shape, pagination, and caveats in a tight sequence. Every sentence carries distinct information (return fields, credits, duplicates, non-publishing) with no filler.

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?

With no output schema available, the description usefully enumerates the returned aweme_list fields (aweme_id, desc, statistics, video, author), plus pagination and credit/confirmation semantics. Combined with full schema coverage and the annotations, an agent has everything needed to invoke it correctly.

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 coverage is 100%, so all six parameters are already documented in the schema, including cursor, confirm, and region semantics. The description restates cursor pagination and confirm behavior without adding format or range detail beyond the structured fields, matching the baseline of 3.

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 ('Searches for TikTok videos under a specific hashtag') and scopes it to topic/trend discovery. This distinguishes it from siblings like tiktok_search_by_keyword, tiktok_search_users, and tiktok_top_search without requiring the agent to open another schema.

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 clear usage context ('finding content by topic or trend') plus operational guidance on pagination and the confirm=true requirement. It does not, however, explicitly contrast when to prefer this over tiktok_search_by_keyword or tiktok_top_search, leaving the closest alternative implicit.

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

tiktok_search_by_keywordSearch by KeywordA

Searches for TikTok videos by keyword or phrase — the general video search across all of TikTok. Returns search_item_list, an array of objects each containing aweme_info with aweme_id, desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count), video info, and author details. Paginate with cursor. TikTok may return duplicate results. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`query`	Yes	Keyword to search for
`cursor`	No	Cursor to get more videos. Get 'cursor' from previous response.
`region`	No	Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	Sort by
`date_posted`	No	Time Frame

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds substantial context beyond them: paid credit consumption, the confirm=true gate, cursor pagination semantics, and the warning that TikTok may return duplicate results years beyond what annotations convey.

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 core purpose, then return shape, pagination, and cost caveats in a logical order. Slightly dense with the nested field enumeration, but every sentence carries operational value and nothing is wasted.

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?

With no output schema, the description carries the return-value burden well by naming search_item_list/aweme_info and its key fields, and it covers pagination, duplicate behavior, and the credit/confirm mechanics. Nothing essential for correct invocation is missing.

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 100%, so every parameter (including the region proxy, sort_by/date_posted enums, and confirm) is already documented in the schema. The description only reinforces pagination via 'Paginate with cursor', adding minimal meaning beyond structured fields, so the baseline 3 applies.

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 (Searches) and resource (TikTok videos by keyword), and explicitly frames it as 'the general video search across all of TikTok', which distinguishes it from siblings like tiktok_search_by_hashtag, tiktok_search_users, and tiktok_search_suggestions without opening any schema.

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?

The phrase 'the general video search across all of TikTok' gives clear context that routes the agent away from hashtag/user search variants, and it flags credit consumption and the confirm=true prerequisite. It stops short of naming a specific alternative tool or stating explicit when-not-to-use conditions, so it is clear context rather than full routing guidance.

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

tiktok_search_suggestionsSearch SuggestionsA

Gets the autocomplete suggestions TikTok shows while someone is typing in search. Returns suggestions, a clean array of suggested search terms and the most useful metadata for each suggestion. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query to get suggestions for
`region`	No	Region code for suggestions
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Goes beyond the annotations by disclosing the paid-credit cost and the confirm=true requirement, plus clarifying that 'read-like POST requests do not publish to social platforms' — useful context given readOnlyHint=false and openWorldHint=true. Not flagged as contradictory since the POST nature is consistent with the non-readonly hint.

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 core purpose, then the return value, then the cost/confirm constraints. Three sentences with minimal waste; the final sentence on POST semantics is slightly tangential but earns its place by pre-empting a safety concern.

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?

With no output schema, the description usefully names the returned `suggestions` array and its content. Combined with credit/confirm caveats, this is sufficient for correct invocation, though it omits any note on result limits or region effects.

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 100%, so the schema already documents all four parameters including confirm and account. The description only reiterates confirm=true and adds no syntax or format meaning beyond the schema, matching the baseline 3.

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 — 'Gets the autocomplete suggestions TikTok shows while someone is typing in search' — which clearly distinguishes it from content-oriented siblings like tiktok_search_by_keyword, tiktok_search_by_hashtag, or tiktok_top_search. An agent can identify the purpose without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a usage prerequisite (consumes paid credits, requires confirm=true) but gives no explicit when-to-use guidance or naming of alternatives such as tiktok_top_search. Usage is implied by the purpose rather than stated comparatively.

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

tiktok_search_usersSearch UsersA

Searches for TikTok users by keyword or name — useful for finding creators or accounts matching a query. Returns users, an array of objects each containing user_info (nickname, unique_id, signature/bio, follower_count, following_count, avatar) and associated items. Paginate with cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response
`query`	Yes	Search query for users
`cursor`	No	Cursor to get more users. Get 'cursor' from previous response.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.4/5.0

Behavior5/5

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

Adds behavior beyond the annotations: the operation is a read-like POST that does not publish to social platforms (reconciling readOnlyHint=false with the lack of side effects), it may consume paid API credits, and it requires confirm=true. These are exactly the operational facts an agent needs and cannot derive from the annotation set.

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 in the first clause, then return shape, pagination, and cost/auth caveats. Efficient overall, though the cursor pagination instruction partially duplicates the schema text and could be trimmed.

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?

With no output schema, the description compensates by describing the return payload (a `users` array whose objects contain `user_info` with nickname, unique_id, signature, follower/following counts, avatar, plus associated `items`), and it covers pagination, credit cost, and the confirm gate. Nothing material is missing for correct invocation.

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 100%, so all five parameters (query, cursor, confirm, trim, account) are already documented in the schema. The description's notes on cursor pagination and confirm largely restate the schema, adding little new semantics, so the baseline 3 applies.

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 (searches), resource (TikTok users), and matching surface (keyword or name), plus the practical intent of finding creators/accounts. This is clearly distinguishable from siblings like tiktok_search_by_keyword, tiktok_search_by_hashtag, and tiktok_top_search, which target content rather than user entities.

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 clear usage context ('useful for finding creators or accounts matching a query'), states the pagination workflow (use cursor from the previous response), and flags the confirm=true prerequisite for the credit-consuming call. It does not explicitly name a competing sibling tool or when-not to use this one, so it falls short of a 5.

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

tiktok_shop_product_detailsProduct DetailsA

Fetches full details for a specific US TikTok Shop product by its URL, including stock levels and affiliate videos. Returns product_info with product_base (title, images, sold_count, price), skus (variants with exact stock counts plus TikTok's sku_name and gtin when available), and product_detail_review (product_rating, review_count, sample reviews). gtin contains gtin_type and gtin_code, or is null when TikTok does not provide a barcode. The response also includes shop_info (shop_name, shop_rating, followers_count) and related_videos (affiliate TikToks promoting the product). This endpoint currently supports the US region only. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the product to get details for.
`region`	No	Region for the product details request. US is the reliable region right now; non-US regions should not be considered reliable and may return `bad_request` or missing product data. Sorry for the inconvenience.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.4/5.0

Behavior5/5

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

Adds substantial context beyond annotations: it warns that the call consumes paid API credits, mandates confirm=true, discloses the hard US-only regional limitation, and explicitly resolves the apparent tension of readOnlyHint=false by noting the read-like POST does not publish to social platforms. Annotations alone would leave the cost and regional constraints invisible.

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-loads purpose, then the return shape, then constraints; every sentence carries information, and the return-field enumeration is warranted since no output schema exists. The first sentence is long and comma-heavy, slightly reducing scanability.

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?

With no output schema, the description fully carries the burden of describing return contents, including the null case for gtin and the nested structure of skus and product_detail_review, and it covers cost, confirmation, and region caveats. Nothing an agent needs to invoke it correctly is missing.

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 100%, so url, region, account, and confirm are already documented; baseline is 3. The description reinforces the region restriction and the confirm requirement, but adds no syntax or format detail beyond the schema text (e.g., accepted URL forms).

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 ('Fetches full details for a specific US TikTok Shop product by its URL') and enumerates the exact payload (product_base, skus, product_detail_review, shop_info, related_videos). The depth of detail (stock counts, affiliate videos) distinguishes it from tiktok_shop_shop_products and tiktok_shop_product_reviews without the agent opening either schema.

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 conditions: US region only, confirm=true required for the credit-consuming call. It does not explicitly name alternatives (e.g., tiktok_shop_product_reviews for review-only needs, tiktok_shop_shop_products for catalog listing), so routing is inferred rather than stated.

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

tiktok_shop_product_reviewsProduct ReviewsA

Fetches customer reviews for a TikTok Shop product by URL or product_id. Returns product_reviews, an array of review objects each with rating, display_text, review_timestamp_fmt, review_user (name, avatar), and sku_specification (variant purchased); also returns total_reviews count and rating_distribution. Paginate with page. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	The URL of the product (required if product_id is not provided)
`page`	No	The page number of the reviews
`region`	No	The region of the product. US is the reliable region right now; non-US regions should not be considered reliable and may return limited or inconsistent review data. Sorry for the inconvenience.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`product_id`	No	The ID of the product (required if url is not provided)

TDQS

A4/5.0

Behavior4/5

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

Description adds useful context beyond annotations: 'Potentially consumes paid API credits; requires confirm=true', and clarifies read-like POST requests do not publish to social platforms. This clarifies credit/billing cost and idempotency-like behavior not fully in annotations (annotations only say readOnlyHint=false and idempotentHint=false). It does not explain failure modes or retry semantics, but the credit warning is a strong piece of behavioral transparency.

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?

Two sentences: first covers the main behavior and return shape; second flags a critical side-effect (credits/confirm) and clarifies it's not a social post. Efficient and front-loaded. Slightly dense return-field list but no fluff.

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 a 6-param tool with no output schema, the description is reasonably complete for identification, return shape, and pagination. However, it does not cover region reliability constraints (which are only in the schema), does not describe error behavior, and does not explain account selection semantics. Adequate but with clear gaps for a paid, region-sensitive tool.

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 description coverage is 100%, so the schema handles naming and basic meaning. Description still adds value by clarifying required-ish inputs ('by URL or product_id') and emphasizing pagination via 'page', plus implies region reliability indirectly (schema covers that fully). Marginal added detail beyond schema, above the baseline 3.

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 (Fetches) and resource (customer reviews for a TikTok Shop product), and identifies the two identifier inputs (URL or product_id). Reads clearly and is distinguishable from siblings like tiktok_comments or tiktok_shop_product_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides some actionable guidance by stating 'Paginate with page', and notes a product URL or id is needed as an identifier. But does not say when this tool should be preferred over similar siblings (e.g. tiktok_shop_product_details), nor does it state when/how to choose url vs product_id beyond the schema, nor caveats around which region to use.

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

tiktok_shop_shop_productsShop ProductsA

Lists all products from a specific TikTok Shop store by its URL. Returns an array of product objects each with title, cover images, url, price info, sold_count, review_count, and rating. Paginate with cursor from the previous response; filter by region; use sort_by=top for best-selling products or sort_by=new_releases for newest products. Non-US shop catalog coverage depends on TikTok exposing that shop in the selected region, so some shops can return not_found outside the US even when they appear in shop search. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The TikTok Shop store URL.
`cursor`	No	Cursor parameter from the previous response to retrieve the next page of products. Omit for the first page.
`region`	No	Region to get shop products from. Defaults to US if not provided. Non-US regions are not reliable right now and may return `not_found` or limited catalog data even when the shop appears in search. Sorry for the inconvenience.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	Sort products by best-selling items (`top`) or newest products (`new_releases`). Defaults to `top`.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false — flagging a mutation-like profile. The description resolves the ambiguity by explaining this is a read-like POST that consumes paid API credits and requires confirm=true, and that it does not publish to social platforms. That is exactly the context annotations cannot convey.

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-loads purpose, then pagination/filtering, then the region caveat, then billing. Efficient and well-ordered, though the final sentence about read-like POSTs is slightly redundant against the annotations and could be trimmed.

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?

Covers return shape, pagination, filtering, sorting, regional caveats, credit cost, and the confirm requirement. For a 6-param tool with no output schema, this is as complete as an agent needs.

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. The description adds value beyond the schema by naming the returned fields (title, cover, url, price, sold_count, review_count, rating) and explaining the cursor/region/sort_by usage in prose, which helps an agent choose values. It doesn't add syntax the schema lacks, so not a 5.

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 (lists) and resource (all products from a TikTok Shop store) and scopes it to a store URL. Distinguishes cleanly from siblings like tiktok_shop_shop_search (which finds shops) and tiktok_shop_product_details (which returns one product).

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?

Explicitly tells the agent when to use sort_by=top vs new_releases, how to paginate with cursor, and when to filter by region. Also names the failure mode (not_found outside US) that should trigger caution, effectively routing to alternatives when the shop isn't US-based.

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

tiktok_shop_shop_searchShop SearchA

Searches TikTok Shop for products matching a keyword query. Returns an array of product objects each with title, cover image, url (product page link), price, sold_count, review_count, rating, and shop_name. Paginate with page; filter by region. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number to retrieve
`query`	Yes	Term you want to search for
`region`	No	Region to search shop products in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent results. Sorry for the inconvenience.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Goes beyond the annotations by disclosing that the call may consume paid API credits, that confirm=true is mandatory, and that the POST is read-like and does not publish to social platforms. That credit/permission context is exactly the kind of behavioral detail annotations (readOnlyHint=false, openWorldHint=true) cannot convey. It stops short of runtime details like rate limits or pagination limits.

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-loads the core action and return shape, then appends pagination, filtering, and cost/confirm caveats in short sentences. Slightly more could be trimmed, but no sentence is wasted.

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?

With no output schema, the description helpfully enumerates the returned fields (title, cover, url, price, sold_count, review_count, rating, shop_name) and covers pagination, region reliability, and the credit/confirm requirement. Minor gaps remain around result limits and error/empty-result behavior.

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 100%, so the schema already documents all five parameters including the enum region caveat and the confirm requirement. The description adds only a light restatement ('Paginate with page; filter by region', 'requires confirm=true'), matching the baseline 3 when structured fields do the heavy lifting.

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 (searches) and resource (TikTok Shop products) tied to a keyword query, which immediately separates it from siblings like tiktok_shop_product_details or tiktok_shop_shop_products. An agent knows exactly what this returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'matching a keyword query' plus notes on paginating with `page` and filtering by region, which is enough to call it correctly. However, it never says when to prefer this over sibling product tools such as tiktok_shop_shop_products, tiktok_search_by_keyword, or tiktok_shop_product_details.

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

tiktok_shop_user_showcaseUser ShowcaseA

Fetches products featured in a TikTok user's public showcase — the products a creator promotes on their profile. Returns an array of product objects each with title, price, images, and shop details. Use POST request if pagination is cutting off too early. Just send the query params in the body. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`cursor`	No	The cursor to the next page of products
`handle`	Yes	The handle of the user
`region`	No	Region to put the proxy in. Non-US TikTok Shop regions are not reliable right now and may return limited or inconsistent showcase data. Sorry for the inconvenience.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.1/5.0

Behavior4/5

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

Goes beyond annotations by disclosing that the call may consume paid API credits, that confirm=true is mandatory, and that the read-like POST does not publish to social platforms. The last point is useful given readOnlyHint=false, which could otherwise mislead an agent into thinking this mutates data. It still doesn't describe rate limits or failure behavior.

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?

The core purpose is stated first, followed by return shape and then two operational notes. Four compact sentences with little waste, though 'Just send the query params in the body' is slightly loose phrasing that overlaps with the pagination sentence.

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?

No output schema exists, yet the description still sketches the return payload (array of product objects with title, price, images, shop details), and it covers the credit/confirm precondition. Minor gaps remain around the account credential parameter and the practical limits of non-US regions, though the latter is documented in the schema.

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 adds real value for two parameters: it explains the cursor pagination workaround (POST fallback) and states the confirm=true requirement, both of which the schema only asserts without motivation. The region and account params get no additional description treatment.

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?

Names a specific verb (fetches) and a precise resource (products in a TikTok user's public showcase), with a clarifying gloss ('the products a creator promotes on their profile'). This scope is distinguishable from sibling shop tools like tiktok_shop_shop_products and tiktok_shop_product_details, which operate on shops rather than creator profile showcases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Offers practical invocation advice ('Use POST request if pagination is cutting off too early. Just send the query params in the body.') and a hard precondition (confirm=true), but never states when to prefer this tool over the shop or profile siblings, nor any when-not conditions. Usage is implied rather than articulated.

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

tiktok_tiktoks_using_songTikToks using SongA

Fetches TikTok videos that use a specific sound or song, identified by its clipId. Returns aweme_list, an array of video objects each with aweme_id, desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count), video info, and author details. Paginate with cursor from the previous response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`clipId`	No	This is clipId. Can be found on a url like so: https://www.tiktok.com/music/That%27s-Who-I-Praise-7370375686554782506, where 7370375686554782506 is the clipId
`cursor`	No	The cursor to get the next page of results.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=true, idempotentHint=false), but the description adds genuinely useful context: it consumes paid API credits, requires confirm=true, and clarifies that the read-like POST does not publish to platforms. That credit/confirmation disclosure is the key behavioral fact an agent needs and is not in the annotations.

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-loads purpose, then return shape, then pagination, then the credit/confirm caveat. Sentences are dense and mostly earn their place, though the aweme_list field enumeration is somewhat long. No filler or redundancy.

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?

With no output schema, the description usefully documents the return payload (aweme_list with aweme_id, desc, statistics, video, author) and the pagination mechanism. Combined with the cost/confirm warning, an agent has enough to invoke and interpret it correctly; only explicit alternative-routing is missing.

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 100%, so the schema already documents clipId, cursor, account, and confirm. The description reinforces clipId and cursor pagination but adds no syntax or format meaning beyond the schema, so baseline 3 is appropriate.

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 (Fetches), resource (TikTok videos using a sound/song), and the key(input clipId). It is distinguishable from siblings like tiktok_get_song_details (song metadata) and tiktok_search_by_hashtag/keyword (different lookup axis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives partial guidance: it explains pagination (use cursor from the previous response) and the confirm=true requirement. However, it never explicitly contrasts with alternatives like tiktok_get_song_details or states when this tool is the right choice over them, leaving the routing implicit.

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

tiktok_top_searchTop SearchA

Searches TikTok's 'Top' results by query — returns both videos and photo carousels, unlike keyword search which only returns videos. Returns items, an array of objects each with id, desc (caption), content_type (video or photo carousel), statistics (play_count, digg_count/likes, comment_count, share_count), video info, and images for carousels. Paginate with cursor. TikTok may return duplicate results. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Keyword to search for
`cursor`	No	Cursor to get more videos. Get 'cursor' from previous response.
`region`	No	Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	Sort by
`publish_time`	No	Time Frame TikTok was posted

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses paid credit consumption, the confirm=true gate, duplicate results risk, the cursor pagination model, and reconciles the readOnlyHint=false annotation by explaining these are read-like POST calls that don't publish to platforms. This is exactly the extra behavioral context annotations alone cannot convey.

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 purpose and sibling differentiation, then output shape, then operational caveats. The output-field enumeration is dense but earns its place since there is no output schema. Slightly long, but no wasted filler.

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?

With no output schema, the description fully describes the return payload (items array with id, desc, content_type, statistics, video, images) plus pagination, duplicate caveat, and credit/confirm requirements. Nothing an agent needs to invoke it correctly is missing.

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 100%, so the schema already documents query, cursor, region, account, confirm, sort_by and publish_time. The description only reinforces cursor pagination and confirm semantics, adding little beyond the structured fields. Baseline 3 applies.

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 ('Searches TikTok's Top results by query') and immediately distinguishes itself from the sibling tiktok_search_by_keyword by noting it returns photo carousels as well as videos. An agent can pick between the two without opening either schema.

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?

Explicitly contrasts this with keyword search and gives a clear condition for using the region proxy parameter. It does not spell out broader when-not-to-use guidance versus other TikTok search siblings (hashtag, users, suggestions), but the key routing decision is covered.

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

tiktok_transcriptTranscriptA

Extracts existing transcripts, captions, or subtitles from a TikTok video by URL. Returns id, url, and transcript as a WEBVTT-formatted string with timestamped text segments. Existing transcripts work for videos of any length. Only the optional AI fallback is limited to videos up to 2 minutes and costs an additional 10 credits when use_ai_as_fallback=true. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	TikTok video URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'
`use_ai_as_fallback`	No	Set to 'true' to use AI when an existing transcript is not found. The AI fallback supports videos up to 2 minutes and costs 10 credits; existing transcripts have no length limit.

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing credit consumption, the hard `confirm=true` requirement, the 2-minute ceiling and 10-credit cost of the AI fallback, and the fact that the read-like POST does not publish to social platforms. These are exactly the behavioral facts an agent needs before invoking a paid endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what is extracted and returned in the first sentence, then adds the cost/limit constraint and the no-publish clarification. Two paragraphs, no filler, each sentence carries distinct information.

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?

With no output schema, the description supplies the return contract (id/url/WEBVTT transcript) as well as auth/credit prerequisites and length limits. Nothing material for correct invocation is missing.

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 100%, and the input schema already documents the AI fallback's 2-minute limit and 10-credit cost as well as the `confirm` requirement, so the description largely restates structured data. It adds the framing that only the fallback is length-limited, but does not explain `account` or `language` beyond 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 verb and resource ('Extracts existing transcripts, captions, or subtitles from a TikTok video by URL') and distinguishes itself from metadata-style siblings like tiktok_video_info. The return shape (`id`, `url`, `transcript` as WEBVTT) further pins down the purpose.

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 clear conditional guidance: existing transcripts work for any length, while the AI fallback only applies to videos up to 2 minutes and costs 10 credits when `use_ai_as_fallback=true`. It does not contrast itself against a sibling tool, but for a leaf extraction tool the when-to-use condition is well covered.

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

tiktok_trending_feedTrending FeedA

Fetches TikTok's trending/For You feed for a given region — useful for discovering viral content and what's currently popular. Returns aweme_list, an array of video objects each with aweme_id, desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count, collect_count), video (playback and download URLs, cover), author info, and image_post_info for photo carousels. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true to get a trimmed response.
`region`	Yes	Where you want the proxy to be. This doesn't mean that you will only see TikToks from this region, you will just see the content that isn't banned in that region.
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations give safety hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real value beyond them: credit consumption, the confirm=true gate, and the reassurance that this read-like POST doesn't publish to social platforms — which pre-empts confusion caused by readOnlyHint=false.

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 purpose, then the return shape, then the cost/safety caveats. The return-field enumeration is dense but earns its place since there is no output schema; nothing is truly wasted.

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?

With no output schema, the description correctly compensates by enumerating aweme_list and the key nested fields (aweme_id, desc, statistics, video, author, image_post_info). Cost and safety behavior are covered; pagination/rate-limit behavior is the only notable omission.

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 coverage is 100%, so all four parameters are already documented in the schema. The description only restates the confirm=true requirement and adds no syntax, defaults, or format detail for region/trim/account, so baseline 3 applies.

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?

Specific verb ('fetches') plus resource ('TikTok's trending/For You feed') plus scope ('for a given region'). It is clearly distinguishable from siblings such as tiktok_search_by_keyword, tiktok_get_popular_creators, and tiktok_profile_videos.

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?

States the use case explicitly ('useful for discovering viral content and what's currently popular') and lists the precondition (paid credits, confirm=true). It doesn't name a specific sibling alternative or when-not-to-use it, so it falls short of a 5.

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

tiktok_video_infoVideo InfoA

Fetches detailed data for a single TikTok video by URL, including its metadata, engagement stats, and optionally its transcript/captions. Returns aweme_detail with desc (caption), statistics (play_count, digg_count/likes, comment_count, share_count, collect_count), video URLs, author info, and music info; also returns transcript in WEBVTT format if get_transcript=true. For no-watermark video URLs, use aweme_detail.video.download_no_watermark_addr.url_list[0] when it exists. If it is missing and aweme_detail.video.has_watermark is false, use aweme_detail.video.play_addr.url_list[0] instead. If has_watermark is true and download_no_watermark_addr is missing, TikTok did not return a no-watermark URL for that video. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	TikTok video URL
`trim`	No	Set to true to get a trimmed response
`region`	No	Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)
`download_media`	No	Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
`get_transcript`	No	Get transcript of the video

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, which the description usefully explains away ('Read-like POST requests do not publish to social platforms'), and it adds cost/credit and confirm=true requirements not present in annotations. Does not mention rate limits or failure behavior, so it stops short of 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?

Front-loads purpose, then outputs, then cost/confirm caveats. The multi-sentence no-watermark fallback logic is verbose but each branch is actionable; no sentence is pure filler, though the URL-selection paragraph could be tightened.

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?

There is no output schema, and the description compensates by naming the returned fields (desc, statistics, video, author, music, transcript in WEBVTT), plus cost and confirm requirements. Only error/edge behavior and caching semantics (left to the schema) are unaddressed.

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 100%, so all eight parameters are already documented in the schema. The description only echoes get_transcript behavior and otherwise describes outputs, not input semantics, so the baseline 3 is appropriate.

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: 'Fetches detailed data for a single TikTok video by URL.' The single-video/by-URL scoping distinguishes it from profile-level siblings (tiktok_profile, tiktok_profile_videos) and from transcript-only tools (tiktok_transcript), and the return contents are enumerated concretely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives operational conditions (paid credits, requires confirm=true) and explains when to prefer the no-watermark vs play_addr URL, but never routes the agent between sibling tools or states when this tool is the wrong choice versus e.g. tiktok_transcript. Usage is implied rather than framed as alternatives.

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

truth_social_postPostA

Fetches a single Truth Social post by URL, returning text, id, created_at, url, content, account details, media_attachments, card link previews, replies_count, reblogs_count, and favourites_count. Set download_media=true to download attached images or video and return permanent Supabase URLs. Only posts from prominent public figures (e.g., Trump, Vance) are accessible without authentication. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Truth Social post URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`download_media`	No	Set to true to download the attached video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.

TDQS

A4.3/5.0

Behavior5/5

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

Adds substantial context beyond annotations: credit consumption, the confirm=true safety requirement, media-download credit cost, auth restrictions on which posts are reachable, and the clarification that read-like POST requests do not publish. This resolves the non-obvious readOnlyHint=false annotation rather than contradicting it.

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-loads the core action and return fields, then layers options and caveats in a logical order. Slightly dense but every sentence carries useful information (return shape, options, auth, credits) with no filler.

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 single-post fetcher with no output schema, the description compensates by listing the returned fields and covering auth, credits, and confirmation constraints. Remaining gaps (error handling, pagination/limits) are minor.

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 100%, so the schema already documents url, account, confirm, and download_media (including credit costs). The description reinforces confirm and download_media meaning but adds no syntax or format details beyond what the structured fields already supply, so baseline 3 applies.

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 ('Fetches a single Truth Social post by URL') and enumerates the return payload, distinguishing it from siblings like truth_social_user_posts and truth_social_profile. An agent can identify the correct tool without opening the schema.

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?

Provides clear situational context: posts from prominent public figures are accessible without auth, download_media=true for media, and confirm=true required. It does not explicitly contrast with sibling tools (e.g., when to use this vs truth_social_user_posts for bulk posts), so it stops short of full when-to-use/alternative routing.

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

truth_social_profileProfileA

Retrieves a Truth Social user's public profile including display_name, username, avatar, header, followers_count, following_count, statuses_count, verified status, website, and created_at. Only prominent public figures (e.g., Trump, Vance) are accessible without authentication; most other accounts will not work. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Truth Social username
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only give generic hints (readOnlyHint=false, openWorldHint=true). The description adds concrete traits beyond them: credit consumption, the confirm gate, partial authentication scope, and a clarification that the read-like POST does not publish to social platforms, which explains the non-read-only hint rather than contradicting it.

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?

Three sentences, front-loaded with the operation and its return fields, then constraints. The field enumeration is long but earns its place given there is no output schema; no filler sentences.

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?

With no output schema, the description compensates by listing returned fields, and it covers authentication scope, cost, and the confirm requirement for a 3-parameter tool. It could still say what happens on failure for non-prominent accounts, but nothing essential for a correct call is missing.

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 100%, so all three parameters (handle, account, confirm) are already documented; the description only restates the credit/confirm behavior. Baseline 3 applies since the schema does the heavy lifting with no added syntax or format detail.

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 (Retrieves) and resource (Truth Social user's public profile) and enumerates the exact fields returned (display_name, followers_count, verified, etc.), which sharply separates it from truth_social_user_posts and truth_social_post. An agent can identify the operation without opening the schema.

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 an explicit usage boundary: only prominent public figures (Trump, Vance) are accessible unauthenticated, and most accounts will not work, plus the confirm=true prerequisite. It lacks a named alternative (e.g., twitter_profile) for the failing case, so it stops short of full routing guidance.

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

truth_social_user_postsUser PostsA

Fetches a paginated list of posts from a Truth Social user, returning text, id, created_at, url, content, account info, media_attachments, card link previews, replies_count, reblogs_count, and favourites_count. Supports pagination via next_max_id and a trim option for lighter responses. Only prominent public figures (e.g., Trump, Vance) are accessible without authentication. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	No	Truth Social username
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`user_id`	No	Truth Social user id. Use this for faster response times. Trumps is 107780257626128497. It is the 'id' field in the profile endpoint.
`next_max_id`	No	Used to paginate to next page

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds meaningful context beyond that: paid credit consumption, the confirm=true gate, the unauthenticated access limit to public figures, and a clarification that the read-like POST does not publish to the platform. It notably addresses why a non-readOnly tool is still non-publishing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with what is fetched and returned, followed by pagination, access constraints, and cost/confirmation notes. No sentence is filler.

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 a six-param fetch tool with no output schema, the description enumerates the return fields, documents pagination and trim, states the auth limitation, and discloses cost plus the confirm=true requirement. Everything an agent needs to call it correctly is present.

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 100%, so the baseline is 3 per the rubric. The description mentions pagination via next_max_id and the trim option for lighter responses, but this largely restates what the schema already documents, adding little new semantic detail.

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 (Fetches), resource (posts), and scope (from a Truth Social user, paginated list), and enumerates the returned fields. An agent can distinguish it from the sibling truth_social_post (single post) and truth_social_profile (profile) without opening a schema.

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 clear operating context: only prominent public figures (e.g., Trump, Vance) are accessible without authentication, and confirm=true is required because the call may consume paid credits. It does not explicitly name an alternative sibling for when a single post (truth_social_post) is wanted, so it stops short of full when/when-not routing.

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

twitch_clipClipA

Fetches detailed data for a Twitch clip by URL, including metadata and direct video URLs. Returns clip id, slug, url, embedURL, title, viewCount, language, durationSeconds, game info, broadcaster details with follower count, thumbnailURL, and videoQualities at multiple resolutions with a signed videoURL for playback. Also includes additional clips from the same broadcaster. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Twitch clip URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and openWorldHint=true, and the description usefully explains the apparent inconsistency ('Read-like POST requests do not publish to social platforms') while disclosing credit cost and the confirm gate. It does not cover pagination or error behavior, but that is minor against the annotation coverage.

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 one dense sentence of return fields, then a short credit/confirm caveat. The return-field enumeration is long but earns its place because there is no output schema.

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?

With no output schema, the description compensates by listing the returned payload fields (viewCount, durationSeconds, broadcaster follower count, videoQualities with signed URLs) and covers the credit/confirm mechanics. Complete enough for an agent to call correctly.

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 100%, so url, account, confirm, and cache_max_age are already documented in the schema; the description adds only the fact that lookup is by URL. Baseline 3 applies since the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetches detailed data for a Twitch clip by URL') and enumerates exactly what comes back, so an agent can distinguish it from twitch_profile or twitch_user_videos. It does not explicitly name the nearest sibling, twitch_clip_transcript, which is the main missing differentiator.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real operational guidance ('Potentially consumes paid API credits; requires confirm=true'), which tells the agent a precondition before calling. It never says when to prefer this over twitch_clip_transcript or kick_clip, so choice between clip-data tools is left to inference.

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

twitch_clip_transcriptClip TranscriptA

Gets a transcript from a public Twitch clip. The endpoint checks Twitch's native captions first. Set use_ai_as_fallback to true to use AI transcription only when native captions are unavailable. Native transcripts cost 1 credit, AI transcripts cost 10 credits, and no credits are charged when no transcript is found. transcript_source is native, ai, or null. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Twitch clip URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`use_ai_as_fallback`	No	Use AI transcription only when native captions are unavailable. Costs 10 credits when an AI transcript is returned. Defaults to false.

TDQS

A4.5/5.0

Behavior5/5

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

Discloses behavior beyond the annotations: native captions are checked first, credit tiers (1 for native, 10 for AI, 0 when none found), the confirm=true gate, and clarifies that the read-like POST does not publish to social platforms – directly resolving the ambiguity created by readOnlyHint=false.

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 core purpose and mechanism, then the cost/confirmation constraints. Efficient overall, though the credit/cost sentences and the final POST clarification are slightly dense for four parameters.

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?

With no output schema, the description usefully defines the return indicator (transcript_source native/ai/null) and the cost/prerequisite semantics. It is nearly self-sufficient; only the exact transcript payload shape is unstated.

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 adds value by linking the parameters to cost and behavior (use_ai_as_fallback triggers 10-credit AI transcription) and by naming the transcript_source output values (native, ai, or null).

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 with scope: 'Gets a transcript from a public Twitch clip.' An agent can distinguish it from twitch_clip (clip metadata) and from transcript tools for other platforms (kick_clip_transcript, youtube_transcript) without opening the schema.

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?

Provides clear operational conditions: set use_ai_as_fallback to true only when native captions are unavailable, and confirm=true is required. It does not, however, explicitly compare against sibling tools or state exclusions (e.g., when to prefer twitch_clip instead).

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

twitch_profileProfileA

Retrieves a Twitch user's public profile by handle, including identity, social links, and content. Returns id, handle, displayName, description, followers count, and linked social accounts (instagram, x, tiktok). Also includes allVideos with game info, duration, and view counts, featuredClips with clip metadata and thumbnails, and similarStreamers. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Twitch handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare it non-read-only, open-world, non-idempotent, non-destructive; the description usefully explains the odd readOnlyHint=false by disclosing that it 'Potentially consumes paid API credits; requires confirm=true' and that read-like POSTs do not publish. That clarifies economics and side effects beyond the annotation flags, though it omits rate limits and the caching behavior that lives only in the schema.

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?

Three sentences, front-loaded with the purpose and then the return fields, then the credit warning. The return enumeration is long but earns its place given no output schema exists; nothing is redundant.

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?

With no output schema, the description carries the return-value burden well by naming the top-level fields and sub-objects. It also covers credit cost and the confirm gate, leaving only minor gaps (caching interplay, pagination/size limits) for an otherwise complete read-tool definition.

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 coverage is 100%, so handle, account, confirm, and cache_max_age are already documented in the schema. The description only restates the confirm requirement and adds no new syntax or semantics for the parameters, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves a Twitch user's public profile by handle') and enumerates the returned content, so the agent knows exactly what it gets. It does not, however, distinguish itself from Twitch siblings like twitch_user_videos or twitch_clip, even though it returns allVideos and featuredClips that overlap with those tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'by handle' and the confirm/credit warning, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative Twitch sibling. The agent must infer that this is the aggregating profile call rather than the narrower video/clip tools.

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

twitch_user_scheduleUser ScheduleA

Fetches a user's schedule by handle, returning a list of scheduled events with start time, end time, title, description, and thumbnail URL. Supports pagination via cursor and a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Twitch handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, and the description adds genuinely useful context beyond them: the call is read-like despite being a POST and does not publish to social platforms, and it may burn paid credits requiring confirm=true. This resolves the main behavioral ambiguity an agent would have from the annotations alone, though it omits rate-limit or failure behavior.

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?

Two tight sentences, front-loaded with what is fetched and what is returned. The credits/confirm warning is appropriately short, though the trailing 'do not publish to social platforms' clause reads as defensive boilerplate that could be folded more tightly.

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?

With no output schema, the description correctly enumerates the return fields, and it covers the credit and confirm requirements. The main gap is the misleading cursor/trim mention, which leaves an agent unsure how pagination is actually driven.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/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 actively muddies parameter semantics: it advertises pagination via cursor and a trim option, yet neither parameter exists in the input schema (only handle, account, confirm). The one useful addition, confirm=true, merely restates the schema description. The phantom-parameter reference makes the description less reliable than the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) plus resource (a user's schedule by handle) and enumerates the returned fields (start time, end time, title, description, thumbnail URL), which no sibling like twitch_profile or twitch_user_videos provides. It does not explicitly name a sibling, so it isn't a fully exemplary 5, but the resource is clearly distinct from everything else in the Twitch group.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description flags operational conditions — paid credits and confirm=true — but never says when to prefer this tool over twitch_profile, twitch_user_videos, or twitch_clip. Usage is implied by the resource name rather than explained.

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

twitch_user_videosUser VideosA

Fetches a list of videos (100 max) for a Twitch user, returning each video's id, slug, url, embedURL, title, viewCount, language, durationSeconds, game info, broadcaster details with follower count, thumbnailURL, and videoQualities at multiple resolutions with a signed videoURL for playback. Supports pagination via cursor and a trim option for lighter responses. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Twitch handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`sort_by`	No	Sort by
`filter_by`	No	Filter by

TDQS

A3.7/5.0

Behavior5/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds valuable context beyond this: paid API credit consumption, the confirm=true requirement, non-publishing read-like POST behavior, pagination via cursor, and a trim option for lighter responses.

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?

Purpose is front-loaded, followed by return fields and then operational constraints. The long field list is justified because there is no output schema, though it makes the description dense.

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?

Given no output schema, the description usefully lists returned fields and covers credits, confirm=true, pagination, and trim behavior. It is nearly complete, though it lacks error handling details and does not clarify the cursor or trim mechanics absent from the schema.

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 100%, so the baseline is 3. The description reinforces confirm=true but does not explain sort_by or filter_by beyond their enum names, and it mentions cursor and trim despite neither appearing in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetches a list of videos for a Twitch user, with a 100 max scope. It does not explicitly distinguish itself from siblings like twitch_clip or twitch_profile, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance relative to alternatives is provided. The operational note about credits and confirm=true is a prerequisite, not routing guidance for selecting this tool over twitch_clip, twitch_profile, or twitch_user_schedule.

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

twitter_communityCommunityA

Retrieves details about a Twitter/X Community by URL. Returns the community name, description, rest_id, join_policy, created_at, member_count, rules, and creator_results with the creator's profile. Also includes members_facepile_results with avatar images of recent members. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Community URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Without the description, readOnlyHint=false would misleadingly suggest a mutating tool; the description resolves this by explaining that read-like POSTs do not publish to social platforms, which is exactly the context annotations cannot convey. It also discloses paid-credit consumption and the confirm gate, though it says nothing about idempotency or rate limits.

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?

Two tight paragraphs, front-loaded with the action and followed by the cost/confirm caveat; the return-field enumeration is dense but useful. Slight redundancy between the description's confirm note and the schema's, but nothing wasted.

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?

With no output schema, the description takes on the burden of describing the return payload and does so explicitly (name, rest_id, join_policy, member_count, rules, creator_results, members_facepile_results). Combined with the credit and confirm disclosure, an agent has what it needs, though channel/error behavior is unstated.

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 100%, so url, account, and confirm are already documented; the description reinforces confirm's credit gate ('requires confirm=true') but adds no format or syntax detail for the url parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

The description states a specific verb and resource ('Retrieves details about a Twitter/X Community by URL') and enumerates the returned fields, so an agent can distinguish it from twitter_profile, twitter_user_tweets, and twitter_community_tweets without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the operating precondition ('requires confirm=true') and a cost warning ('potentially consumes paid API credits'), which is real usage guidance. However, it never names the obvious alternative (twitter_community_tweets) or states when to pick this tool over another Twitter tool, so routing is left implicit.

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

twitter_community_tweetsCommunity TweetsA

Fetches tweets posted within a Twitter/X Community by URL. Returns an array of tweets, each with id, full_text, view_count, favorite_count, retweet_count, reply_count, bookmark_count, quote_count, created_at, and source. Each tweet includes a user object with the author's name, screen_name, avatar, followers_count, and is_blue_verified status. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Community URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is partly covered. The description adds genuinely new behavioral context beyond annotations: paid credit consumption, the confirm=true gating, and the reassurance that the read-like POST does not publish to social platforms. It stops short of describing rate limits or pagination.

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?

Three sentences, front-loaded with purpose and input, followed by return fields and then the cost/confirm caveats. The return-field enumeration is long but justified because no output schema exists; nothing is redundant.

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?

With no output schema, the description usefully enumerates the returned tweet and user fields, and it covers the credit/confirm constraints. It omits pagination limits and authentication expectations, which keeps it just short of fully complete for a paid API call.

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 100%, so all three parameters (url, account, confirm) are already documented in the schema. The description only reiterates the URL input and the confirm requirement, adding no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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?

The description states a specific verb and resource ('fetches tweets posted within a Twitter/X Community by URL'), and the community-scoped qualifier distinguishes it from siblings like twitter_user_tweets and twitter_community without ambiguity. An agent can tell what it returns and where the input comes from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a hard precondition ('requires confirm=true') and warns about credit consumption, which is useful usage context. However, it never states when to choose this over the sibling twitter_community or twitter_user_tweets, so selection guidance is only implied by the resource scope.

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

twitter_profileProfileA

Retrieves a Twitter user's profile by handle, including account metadata and statistics. Returns name, screen_name, description, followers_count, friends_count, statuses_count, favourites_count, location, profile_image_url_https, and is_blue_verified. Also includes verification_info, tipjar_settings, highlights_info, and creator_subscriptions_count. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	Yes	Twitter handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.2/5.0

Behavior4/5

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

Adds context beyond the annotations: credit consumption, the confirm=true gate, and an explicit clarification that despite the write-like POST verb the call does not publish to social platforms — which reconciles the readOnlyHint=false flag. It does not cover failure modes or credit-refund behavior, but for this tool that is a minor gap.

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-loads the core purpose and return fields, then the operational caveats. The trailing 'Read-like POST requests do not publish to social platforms' sentence is slightly awkward and appends after the credits note, but every sentence carries information and nothing is filler.

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?

With no output schema, the description carries the return-value burden and discharges it by enumerating both the standard profile fields and the extras (verification_info, tipjar_settings, highlights_info, creator_subscriptions_count). Combined with the cost/confirm disclosure and 100% schema coverage, an agent has everything needed to call it correctly.

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 100%, so handle, account, confirm, and cache_max_age are already fully documented in the schema. The description restates confirm=true and the credit cost but adds no new syntax or format detail, so the baseline 3 applies.

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 ('Retrieves a Twitter user's profile by handle') and enumerates the returned metadata, which cleanly distinguishes it from siblings like twitter_user_tweets, twitter_tweet_details, or other platforms' *_profile tools. An agent can identify the target and output without opening the schema.

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 a concrete precondition ('requires confirm=true') and a cost signal ('potentially consumes paid API credits'), so the agent knows the call is gated and metered. It does not, however, name an alternative tool or state when NOT to use it (e.g., versus twitter_user_tweets for tweet data), so it falls short of full routing guidance.

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

twitter_transcriptTranscriptA

Extracts the transcript from a Twitter video tweet using AI-powered transcription. The video must be under 2 minutes long. Returns a success flag and the full transcript text. This endpoint is slower than others due to the AI processing step. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Tweet URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A4.7/5.0

Behavior5/5

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

Adds substantial context beyond annotations: AI processing latency, potential paid credit consumption, confirm=true requirement, and that read-like POST requests do not publish to social platforms. It also states the return shape. Annotations already flag not read-only and open-world, but the description enriches the operational and cost profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then constraints, return value, performance note, and credit/confirm requirements. Every sentence adds a distinct operational fact with no filler.

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?

Given the rich input schema and absence of an output schema, the description covers purpose, input constraints, side effects, return shape, and confirmation needs. Nothing critical for correct invocation 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 schema already documents all four parameters. The description adds the non-schema constraint that the URL must point to a Twitter video tweet under 2 minutes and reinforces the confirm=true requirement, though it does not elaborate on account or cache_max_age.

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: extracts a transcript from a Twitter video tweet using AI. It clearly distinguishes itself from sibling transcript tools such as youtube_transcript, facebook_transcript, and instagram_transcript by platform and input type.

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?

The description gives clear constraints: the video must be under 2 minutes, the endpoint is slower, and confirm=true is required. It does not explicitly name alternatives or when-not-to-use cases, but the stated prerequisites effectively scope usage.

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

twitter_tweet_detailsTweet DetailsA

Retrieves detailed information about a specific tweet by URL, including the author's profile and engagement metrics. Returns rest_id, full_text, views count, favorite_count, retweet_count, reply_count, bookmark_count, quote_count, created_at, source, and media entities. Supports a trim parameter for a lighter response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Tweet URL
`trim`	No	Set to true for a trimmed down version of the response
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the description earns credit by explaining that the read-like POST does not publish to social platforms and that the call consumes paid credits and requires confirm=true. It stops short of describing rate limits or what a failed credit charge does, keeping it below 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?

Three front-loaded sentences with no filler; the field enumeration is slightly long but directly useful to an agent since no output schema exists.

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?

With no output schema and a 5-parameter credit-consuming tool, the description usefully names the return fields and the confirm/credit requirement. It omits cache behavior and account selection, which are covered in the schema, so it is largely complete.

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 100%, so the baseline is 3; the description only restates the trim parameter's lighter-response behavior already documented in the schema and adds nothing about account or cache_max_age semantics.

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 ('Retrieves detailed information about a specific tweet by URL') and enumerates the returned fields, making it easy to distinguish from siblings like twitter_transcript or twitter_user_tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It surfaces prerequisites (requires confirm=true, consumes paid credits) but never states when to choose this over alternatives such as twitter_transcript or twitter_profile, nor when a plain tweet fetch is inappropriate; usage is only implied.

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

twitter_user_tweetsUser TweetsA

Fetches tweets from a Twitter user's profile by handle. Note: Twitter publicly returns only ~100 of the user's most popular tweets, not chronological or latest. Each tweet includes rest_id, full_text, views count, favorite_count, retweet_count, reply_count, bookmark_count, quote_count, created_at, media entities, and url. Supports a trim parameter for a lighter response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`trim`	No	Set to true for a trimmed down version of the response
`handle`	Yes	Twitter handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A4/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses the ~100-most-popular (non-chronological) return behavior, enumerates the returned fields, flags that the call consumes paid API credits, requires confirm=true, and explicitly reconciles the readOnlyHint=false annotation by noting read-like POSTs do not publish to social platforms. That last point is exactly the context an agent needs to trust the tool.

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 core action, then the important return caveat, then supporting details. The field enumeration is long but justified because there is no output schema; nothing reads as filler, though the sentence could be tightened.

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?

With no output schema, the description correctly compensates by listing the returned fields and the popularity caveat. Combined with the credit/confirm warning and the read-only clarification, an agent has everything needed to call this successfully.

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 100%, so the schema already documents trim, handle, account, and confirm; baseline is 3. The description restates the trim effect ('lighter response') and the confirm requirement, but adds no syntax or format detail beyond what the schema provides, and never mentions the account parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Fetches tweets from a Twitter user's profile by handle.' This is clearly distinct in scope from twitter_profile (profile info), twitter_tweet_details (a single tweet), and twitter_community_tweets (community timelines), though the description never names a sibling to route the agent explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the resource scope, and the caveat that only ~100 most-popular tweets are returned (not chronological/latest) is a valuable context signal for deciding whether this tool fits a request. However, no alternatives or explicit when/when-not conditions are stated.

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

youtube_channel_community_postsChannel Community PostsA

Fetches community posts from a YouTube channel's Posts tab, including post ID, URL, content, images, attached video, like count, publish time, channel info, and a continuationToken when YouTube has more results. Pass a handle or channelId for the first page, then pass continuationToken to page through more posts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	YouTube channel handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	YouTube channel ID
`continuationToken`	No	Continuation token to get more community posts. Get 'continuationToken' from previous response.

TDQS

A4.5/5.0

Behavior4/5

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

Adds real value beyond annotations: it discloses that the call 'Potentially consumes paid API credits' and 'requires confirm=true', and resolves the odd readOnlyHint=false annotation by explaining that read-like POST requests do not publish to social platforms. It doesn't cover rate limits or error behavior, but the credit/auth disclosure is substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then the pagination mechanic, then the credit/confirm caveat. Every sentence earns its place with no filler.

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 a paginated read tool with no output schema, the description covers return fields, pagination, credit cost, and the confirm requirement. An agent has everything needed to invoke it correctly.

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 clarifies the relationship between parameters (handle/channelId for the first page vs continuationToken for paging) and the confirm gating, adding meaning beyond the field descriptions.

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 (fetches) and resource (community posts from a YouTube channel's Posts tab), and enumerates the returned fields. This clearly distinguishes it from siblings like youtube_channel_videos, youtube_channel_shorts, and youtube_community_post_details.

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?

Explicitly describes the request flow: 'Pass a handle or channelId for the first page, then pass continuationToken to page through more posts.' This is clear operational context, though it doesn't name alternatives or when-not-to-use this tool versus youtube_community_post_details.

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

youtube_channel_detailsChannel DetailsA

Retrieves comprehensive YouTube channel profile data including name, avatar images, subscriber count (subscribers), total video and view counts, join date, tags, and linked social accounts like Twitter and Instagram. Accepts a channelId, handle, or full channel URL as input. Returns channel metadata such as country, email, and external store links when available. Contact fields come from the submitted public profile. To request removal of your own information from Scrape Creators results, email support@scrapecreators.com with the profile URL. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	No	YouTube channel URL. Can pass a channelId, handle or url
`handle`	No	YouTube channel handle. Can pass a channelId, handle or url
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	YouTube channel ID. Can pass a channelId, handle or url
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.6/5.0

Behavior4/5

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

Annotations only mark openWorldHint and non-idempotent, so the description carries real weight by disclosing paid-credit consumption, the confirm=true gate, cache-vs-live behavior, and that read-like POSTs do not publish. The 'read-like' phrasing sits in mild tension with readOnlyHint=false but clarifies rather than contradicts it. It still doesn't say what happens on missing/invalid identifiers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core capability and field list are front-loaded and efficient, but the trailing sentences about contact-field provenance and emailing support@scrapecreators.com for data removal are legal boilerplate that doesn't help an agent select or invoke the tool.

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 6-parameter tool with no output schema, the description is nearly complete: it covers credits, confirmation, caching semantics, and input flexibility, and annotations supply the safety profile. Only minor gaps remain around failure behavior and the exact credit cost per call.

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 100% and the schema already documents the interchangeable channelId/handle/url inputs, the account selector, confirm, and the cache_max_age enum. The description restates the accepted identifier forms and the confirm requirement without adding format or syntax detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Retrieves comprehensive YouTube channel profile data') and enumerates the retrieved fields, so an agent immediately knows this returns channel-level metadata rather than videos or playlists. It does not explicitly contrast itself with nearby siblings like youtube_channel_videos or youtube_search, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states prerequisites ('requires confirm=true', credit consumption, caching) and the accepted input forms, which implies when the call is appropriate. However, it never says when to prefer this over youtube_search or the other youtube_channel_* tools, so routing guidance is left to inference.

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

youtube_channel_livesChannel LivesA

Fetches live streams and past streams from a YouTube channel's Live tab, including title, URL, thumbnail, view count, publish time, duration, and a continuationToken when YouTube has more results. Pass a handle or channelId for the first page, then pass continuationToken to page through more lives. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	YouTube channel handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	YouTube channel ID
`continuationToken`	No	Continuation token to get more lives. Get 'continuationToken' from previous response.

TDQS

A4.1/5.0

Behavior4/5

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

Adds meaningful traits beyond the annotations: it consumes paid API credits and requires confirm=true, and it clarifies that the write-shaped POST is 'read-like' and does not publish to social platforms. This resolves the tension with readOnlyHint=false by explaining the credit-consuming side effect rather than contradicting it.

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-loads the purpose and return fields, then usage, then the credit/confirm warning. Every sentence carries information, though the final sentence packaging of credit and publishing caveats is slightly dense.

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?

With no output schema, the description usefully enumerates returned fields (title, URL, thumbnail, view count, publish time, duration, continuationToken) and covers the confirm/credit requirement. An agent has nearly everything needed, with only sibling-selection guidance 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 description coverage is 100%, so the baseline is 3, but the description adds the workflow semantics: handle/channelId seed the first page while continuationToken drives pagination. This relational guidance goes beyond the per-field schema text.

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 ('Fetches') and resource ('live streams and past streams from a YouTube channel's Live tab'), listing concrete return fields. The 'Live tab' scope cleanly distinguishes it from siblings like youtube_channel_videos, youtube_channel_shorts, and youtube_channel_playlists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the calling flow: use handle/channelId for the first page, then continuationToken to page through more. It also flags the confirm=true requirement. However, it never says when to choose this tool over sibling options such as youtube_channel_videos, leaving the when-to-use decision implied.

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

youtube_channel_playlistsChannel PlaylistsA

Fetches playlists from a YouTube channel's Playlists tab, including playlist ID, title, thumbnail, video count, channel info, playlist URL, and a continuationToken when YouTube has more results. Pass a handle or channelId for the first page, then pass continuationToken to page through more playlists. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`handle`	No	YouTube channel handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	YouTube channel ID
`continuationToken`	No	Continuation token to get more playlists. Get 'continuationToken' from previous response.

TDQS

A4.2/5.0

Behavior4/5

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

Annotations alone (readOnlyHint=false) would mislead an agent into assuming a mutation; the description explains that these are read-like POSTs that do not publish to social platforms, and adds the credit-consumption and confirm=true requirements. It stops short of error/rate-limit behavior, so not 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?

Front-loads the core action and return fields, then adds pagination and the credit/confirm caveat. The field enumeration runs long in the first sentence, but every part is functional.

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?

With no output schema, the description compensates by listing the returned fields, and it covers pagination, credit cost, and the confirm requirement — everything needed to invoke this tool correctly given its complexity.

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 coverage is 100%, so all five parameters are documented in the schema itself, including continuationToken usage. The description's pagination note largely restates the schema rather than adding syntax or format details, so baseline 3 applies.

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 (fetches) and resource (playlists from a YouTube channel's Playlists tab) and enumerates the returned fields. An agent can distinguish it from youtube_playlist (single playlist) and youtube_channel_videos without opening either schema.

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 a handle or channelId for the first page, then continuationToken to page further, and notes the credit cost and confirm=true prerequisite. It does not name alternatives, but the when/how is clear.

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

youtube_channel_shortsChannel ShortsA

Retrieves a paginated list of short-form videos (Shorts) from a YouTube channel, including each short's title, URL, view count (views), likes, comments, description, and publish date. publishDate is a full ISO 8601 timestamp with an offset when YouTube exposes the exact publish time; otherwise it is null. It does not return date-only strings. Supports sorting by newest or popular; use the continuationToken to page through all results. Returns data in the shorts array. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`sort`	No	Sort by newest or popular
`handle`	No	Can pass channelId or handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	Can pass channelId or handle
`continuationToken`	No	Continuation token to get more videos. Get 'continuationToken' from previous response.

TDQS

A3.9/5.0

Behavior4/5

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

With readOnlyHint=false set, the description usefully clarifies that this is a read-like POST that does not publish to social platforms, and warns about credit consumption and the confirm=true gate — real behavior beyond the annotations. It also explains null-vs-ISO-8601 semantics for publishDate, though it doesn't cover rate-limit or failure behavior.

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 primary purpose and return shape, then a short operational paragraph. Sentences earn their place, though the publishDate null explanation is slightly verbose relative to its importance.

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?

No output schema exists, and the description compensates by naming the return array (shorts) and the per-item fields plus publishDate semantics. Credit cost, the confirm gate, and paging are all covered; only failure/edge behavior is absent.

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 100%, so the schema already documents handle/channelId, account, sort, confirm, and continuationToken. The description largely restates those (sorting, token paging, confirm) without adding format or precedence detail, which is the expected baseline when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (retrieve paginated Shorts from a YouTube channel) and enumerates the returned fields, so an agent can tell it apart from sibling list tools like youtube_channel_lives or youtube_channel_community_posts. It never explicitly names an alternative sibling (e.g., youtube_channel_videos or youtube_trending_shorts), so differentiation is implied rather than stated.

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 operational context: sorting options ('newest' or 'popular'), how to page with continuationToken, and a hard prerequisite (confirm=true because it consumes paid credits). It lacks an explicit when-to-use-this-vs-sibling rule, which keeps it below 5.

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

youtube_channel_videosChannel VideosA

Fetches a paginated list of videos uploaded by a YouTube channel, including each video's title, URL, thumbnail, view count (views), publish date, duration, and description. Supports sorting by latest or popular, and use the continuationToken to page through all results. Optionally include extras like like count, comment count, and descriptions for each video. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`sort`	No	Sort by latest or popular
`handle`	No	YouTube channel handle
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`channelId`	No	YouTube channel ID
`includeExtras`	No	This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. Honestly, if you use this param, the error rate is higher. We might deprecate this param in the future.
`continuationToken`	No	Continuation token to get more videos. Get 'continuationToken' from previous response.
`is_paid_promotions`	No	Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement search surface. This returns normal YouTube videos where the creator declared paid promotion. Cannot be combined with filter, uploadDate, sortBy, type, duration, or includeExtras.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations only flag readOnlyHint=false, openWorldHint=true, and destructiveHint=false; the description adds genuinely new context by disclosing credit consumption, the confirm=true gate, and that read-like POSTs do not publish to social platforms. That last clause usefully reconciles the non-read-only annotation with the perceived safety of the call. No rate limits or failure modes are described, though.

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 what is returned, then a compact second paragraph covering cost/confirmation/behavior. Two sentences carry a lot of information with no filler, though the caveat about extras slightly duplicates the schema text.

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 an 8-parameter tool with no output schema, the description covers return shape, paging, sorting, and the credit/confirm gate, which is enough for correct invocation. Missing are details on required identifiers (handle vs channelId choice) and what happens on invalid channel input.

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 100%, so all 8 parameters are already documented in the schema, including the enum for sort and the caveats on includeExtras. The description restates sort options, continuationToken paging, and includeExtras without adding syntax, defaults, or constraints beyond what the schema provides. Baseline 3 applies.

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 ('Fetches a paginated list of videos uploaded by a YouTube channel') and enumerates the returned fields (title, URL, thumbnail, views, publish date, duration, description). This scope cleanly separates it from siblings like youtube_channel_shorts, youtube_channel_lives, and youtube_channel_playlists without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives operational preconditions (paid API credits, requires confirm=true, use continuationToken to page) but never says when to choose this over youtube_search, youtube_channel_shorts, or the single-video endpoint. Usage is implied rather than contrasted.

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

youtube_comment_repliesComment RepliesA

Fetches replies to a specific comment on a YouTube video, including each reply's text content, author details (name, channel ID, avatar, verified/creator status), like count, and publish date. Requires a continuationToken obtained from the 'repliesContinuationToken' field on comments returned by the Comments endpoint. Supports paginating through additional replies with the continuationToken returned in each response. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`continuationToken`	Yes	Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate.

TDQS

A4.2/5.0

Behavior4/5

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

Adds context the annotations do not carry: potential paid credit consumption, the confirm=true gate, and the clarification that these read-like POSTs do not publish to social platforms (resolving the tension with readOnlyHint=false). No detail on rate limits or error behavior, but this is meaningful disclosure beyond the annotation set.

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 purpose, then token sourcing, pagination, and the credit/confirm caveat. The field enumeration is long but justified because there is no output schema. Slightly dense but every clause earns its place.

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?

With no output schema, the description carries the return-value burden by listing reply text, author details, like count, and publish date. Combined with the token prerequisite, pagination behavior, and credit/confirm constraints, an agent has everything needed to call this correctly.

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 100%, so account, confirm, and continuationToken are already documented in the schema. The description restates the token sourcing and pagination semantics without adding new syntax or format detail, so it sits at the baseline.

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 ('Fetches replies to a specific comment on a YouTube video') and enumerates the returned fields, so it is unambiguous against the sibling youtube_comments (top-level comments) and against the platform-parallel tiktok_comment_replies/instagram_comment_replies.

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 a concrete prerequisite chain: the required continuationToken must come from the 'repliesContinuationToken' field of the Comments endpoint, or from a prior replies response to paginate further. It does not state when to prefer this over sibling reply tools, but the workflow context is clear.

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

youtube_commentsCommentsA

Fetches comments and replies from a YouTube video, including each comment's text content, author details, like count, reply count, and publish date. Supports ordering by top or newest, and paginating with continuationToken. Limited to approximately 1,000 top comments or 7,000 newest comments. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	YouTube video URL
`order`	No	Order of comments
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`continuationToken`	No	Continuation token to get more comments. Get 'continuationToken' from previous response.

TDQS

A3.8/5.0

Behavior4/5

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

Beyond the annotations (destructiveHint=false, openWorldHint=true), the description adds meaningful operational context: it consumes paid credits, requires confirm=true, and is capped at ~1,000 top / 7,000 newest comments. It also preempts confusion about the non-readOnly POST by noting it does not publish to social platforms. It stops short of describing error/pagination failure behavior, so not 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by ordering/pagination, limits, and cost/auth constraints. All four sentences carry distinct, non-redundant information with no filler.

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?

With no output schema, the description compensates by listing the returned fields and the retrieval caps, and it covers the credit/confirm requirements. The one notable gap is behavior on missing or expired continuation tokens, but overall it is complete enough to invoke correctly.

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 100%, so all five parameters are already documented in the schema. The description restates 'ordering by top or newest' and continuationToken but adds no syntax, format, or edge-case detail beyond the schema, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Fetches comments and replies from a YouTube video') and enumerates the returned fields (text, author, like count, reply count, publish date). It is distinct from generic siblings, though it does not explicitly name youtube_comment_replies as the alternative for reply retrieval, which keeps it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It surfaces a real precondition ('requires confirm=true', credit consumption) and describes ordering/pagination options, so usage is implied. However, it never states when to choose this tool over youtube_comment_replies or youtube_transcript, leaving the routing decision to inference.

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

youtube_community_post_detailsCommunity Post DetailsA

Retrieves the full details of a YouTube community post, including its text content, attached images, like count, publish date, and associated channel info. Also returns a linked video if the post includes one. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL of the YouTube community post to get
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.8/5.0

Behavior4/5

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

Adds context the annotations do not: it consumes paid API credits, needs confirm=true, and clarifies that the read-like POST does not publish to any social platform. That last point meaningfully de-risks the readOnlyHint=false / openWorldHint=true annotation by explaining the write-like transport is non-publishing. It stops short of describing cost magnitude or failure modes.

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?

Two sentences, front-loaded with the purpose and the returned fields, followed by cost/safety notes. Dense but every clause earns its place; no filler or redundancy.

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?

There is no output schema, and the description compensates by listing the fields that come back, so an agent knows what to expect. Cost, confirmation requirement, and non-publishing behavior round out the picture for a single-record detail tool.

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 coverage is 100%, so the schema already documents url, account, and confirm. The description only echoes the confirm=true credit requirement and adds no new meaning for the url or account parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves the full details of a YouTube community post') and enumerates the returned fields (text, images, like count, publish date, channel info, linked video). This clearly separates it from the listing sibling youtube_channel_community_posts, though the sibling is not named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete prerequisite ('requires confirm=true') for the credit-consuming call, which is real usage guidance. However, it never states when to reach for this tool versus youtube_channel_community_posts or how to obtain the post URL, leaving usage largely implied.

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

youtube_playlistPlaylistA

Retrieves all videos in a YouTube playlist, including the playlist title, owner info, total video count, and each video's title, URL, thumbnail, duration, and channel. Accepts the playlist ID found in the 'list' URL parameter. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`playlist_id`	Yes	The ID of the YouTube playlist. In the YouTube URL it will be the 'list' parameter.

TDQS

A3.7/5.0

Behavior4/5

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

With annotations present, the description adds meaningful context beyond them: credit consumption, the required confirm flag, and an explicit explanation that the read-like POST does not publish to social platforms (which reconciles the otherwise puzzling readOnlyHint=false). It still doesn't describe pagination behavior or result-size limits for large playlists.

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?

Return payload is front-loaded in the first sentence, with the parameter hint and the credit/confirm caveats following. Three sentences, each doing work, with only mild redundancy between the 'confirm=true' mention and the read-like POST clarification.

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?

There is no output schema, so listing the returned fields is genuinely necessary and it does so. With a 100% schema and annotations covering safety, the only remaining gap is pagination/volume behavior for large playlists.

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 100%, and the description largely restates the schema's own note that playlist_id is the YouTube URL 'list' parameter. The confirm requirement is surfaced, but no additional syntax or format detail is offered, so this sits at the baseline for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Retrieves all videos in a YouTube playlist') and enumerates the returned fields, so the agent knows exactly what it gets back. It does not differentiate itself from the closest sibling, youtube_channel_playlists (which lists playlists rather than their contents), so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a hard invocation precondition ('requires confirm=true') and warns about paid credits, which is real usage guidance. However, it never says when to prefer this over youtube_channel_playlists or youtube_channel_videos, so alternative selection is left to inference.

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

youtube_searchSearchA

Searches YouTube by keyword query and returns matching videos, channels, playlists, shorts, shelves, and live streams. Each video result includes title, URL, thumbnail, view count (views), publish date, duration, channel info, and badges. Supports filtering by upload date, sorting by relevance or popularity, and paginating with continuationToken. Set is_paid_promotions=true to search YouTube videos with the paid product placement / sponsorship disclosure. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`type`	No	Type of content to search for
`query`	Yes	Search query. For stricter title matching, use YouTube's intitle: operator, for example intitle:"Foursquare Swarm". Quoted queries by themselves may still be broadened by YouTube when no fresh exact matches are available.
`region`	No	2 letter country code of the country to put the proxy in.
`sortBy`	No	Sort by
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`duration`	No	Duration of the video. Only applies to videos (not shorts).
`uploadDate`	No	Upload date
`includeExtras`	No	This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly.
`continuationToken`	No	Continuation token to get more videos. Get 'continuationToken' from previous response.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations alone leave the agent puzzling over readOnlyHint=false for a search, but the description resolves this by stating it consumes paid API credits, requires confirm=true, and that 'Read-like POST requests do not publish to social platforms.' It also flags that includeExtras slows the response. This adds real behavioral context beyond the annotations, though it omits rate-limit or failure behavior.

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?

It is front-loaded with the core purpose and return shape, then layers filters and the credit/confirm caveat. Most sentences earn their place, though the dangling is_paid_promotions clause adds noise without a corresponding schema field.

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 10-parameter, no-output-schema search tool, the description compensates well by enumerating returned fields (title, URL, view count, duration, channel, badges) and covering the paid-credit/confirm mechanic. The only gap is the stray parameter reference and no explicit guidance on the sibling tools.

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 coverage is 100%, so the baseline is 3. The description reiterates filtering/sorting/pagination semantics but adds little beyond the schema fields, and it references an is_paid_promotions parameter that does not appear in the schema (which sets additionalProperties:false), which is a mild inconsistency rather than added clarity.

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?

The description states a specific verb (searches) and resource (YouTube by keyword) and enumerates the returned result types (videos, channels, playlists, shorts, shelves, live streams). Combined with the sibling list (youtube_search_by_hashtag, youtube_search_typeahead, youtube_channel_videos), an agent can tell this is the general keyword search apart from specialized siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It describes capabilities (filter by upload date, sort by relevance/popular, paginate) but never states when to prefer this over youtube_search_by_hashtag, youtube_search_typeahead, or youtube_channel_videos. Usage is implied by the keyword-search framing rather than explicitly guided, so it stays at the minimum-viable level.

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

youtube_search_by_hashtagSearch by HashtagA

Searches YouTube for content matching a specific hashtag and returns matching videos with title, URL, thumbnail, view count (views), publish date, duration, and channel info. Supports pagination via continuationToken and filtering to return all content types or only shorts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`type`	No	Search for all types of content or only shorts
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`hashtag`	Yes	Hashtag to search for
`continuationToken`	No	Continuation token to get more videos. Get 'continuationToken' from previous response.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false and openWorldHint=true; the description earns credit by explaining the cost/auth dimension (paid credits, confirm=true) and by disambiguating the read-like POST so the agent is not misled by a non-read-only hint. It omits rate limits and pagination termination behavior.

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?

Two tight sentences, front-loaded with purpose and returns before the cost/confirm caveat. Dense but every clause carries information; only minor tightening possible.

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?

With no output schema, the description usefully enumerates the returned fields, and annotations plus 100% schema coverage carry the rest. Coverage is strong; only rate/credit-limit specifics are absent.

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 100%, so the schema already documents all five parameters including the enum and the account/confirm semantics. The description only restates pagination and the type filter, adding little beyond the structured fields; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: searching YouTube by hashtag, plus the exact result fields returned (title, URL, thumbnail, views, publish date, duration, channel). The platform and resource distinguish it from tiktok_search_by_hashtag, though the description never names an alternative sibling to disambiguate.

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 clear operational context: pagination via continuationToken, the all/shorts filter, and the hard requirement confirm=true with a note that calls may consume paid credits. It stops short of naming when to prefer youtube_search or tiktok_search_by_hashtag instead, so no explicit alternatives or exclusions.

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

youtube_search_typeaheadSearch TypeaheadA

Returns the live search suggestions YouTube displays while a user types. Each result includes the suggested text and whether it is a normal query or a channel. When YouTube returns a channel suggestion, the response also includes its public channel ID, handle, name, and thumbnail. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Partial or complete YouTube search query
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false, openWorldHint=true, and non-idempotent, but the description adds meaningful context the annotations cannot: it consumes paid API credits, requires confirm=true, and explicitly explains that the read-like POST does not publish to social platforms — resolving why a read operation is marked non-read-only.

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?

Four sentences, front-loaded with what is returned and followed by cost/prerequisite information. The detail on channel suggestion fields is slightly padded but every sentence carries relevant information.

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?

With no output schema, the description usefully describes the return shape (suggested text, query vs channel, and channel metadata) and discloses the credit/confirm cost model. Only minor omissions remain, such as result count or rate-limit behavior.

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 100% and already documents query, account, and confirm. The description reinforces the confirm=true precondition but adds no new syntax or semantic detail beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns the live search suggestions YouTube shows while typing, and describes result shape (query vs channel, with channel ID/handle/name/thumbnail). It is clearly distinguishable from youtube_search or youtube_search_by_hashtag, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the nature of autocomplete (call while a user is typing), and the description flags cost/prerequisite ('requires confirm=true'), but it gives no explicit when-to-use vs when-not guidance and no routing to alternatives such as youtube_search.

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

youtube_transcriptTranscriptA

Retrieves publicly available captions, subtitles, or transcripts from a YouTube video or Short. Returns both a timestamped transcript array with start/end times and a plain-text version in transcript_only_text. Supports specifying a language code. Videos of any length are supported when YouTube exposes public captions. This endpoint does not use the two-minute AI transcription fallback. If no matching caption track is available, the transcript fields return null. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	YouTube video or short URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	Language code, ie 'en', 'es', 'fr' or 'en-US'. Overrides the default track selection unless original_audio=true. If omitted, prefers captions matching the original spoken language when YouTube identifies the original audio. If that metadata is unavailable or ambiguous, prefers an auto-generated caption, otherwise the first caption track. If the requested or identified original language has no matching captions, the transcript will be null and no credits are charged.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)
`original_audio`	No	Set to true to return captions only in the original spoken language identified by YouTube. Takes precedence over language. If the original audio cannot be reliably identified or has no matching captions, transcript, transcript_only_text, and language are null and no credits are charged. No extra lookup or credit cost; a returned transcript costs the usual 1 credit. Omit or set to false for the existing default selection.

TDQS

A4.1/5.0

Behavior4/5

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

Adds substantive behavior beyond annotations: credit consumption, the confirm=true gate, null returns when no caption track matches, and the assurance that read-like POST requests do not publish to social platforms. Annotations already flag readOnlyHint=false and openWorldHint=true, so this context meaningfully lowers agent uncertainty about cost and side effects.

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-loads what is retrieved and the return shape, then adds cost and safety notes in a compact block. Slightly dense but every sentence carries information; no filler.

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?

With no output schema, the description compensates by naming the returned fields (timestamped array with start/end times, transcript_only_text) and the null case. Combined with the credit/caching notes in the schema, an agent has enough to call it correctly, though pagination or response envelope details are not addressed.

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 100%, so url, language, confirm, cache_max_age, and original_audio semantics are already fully documented in the schema. The description mentions only language-code support generically, adding little beyond what the schema provides; baseline 3 is appropriate.

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 ('Retrieves publicly available captions, subtitles, or transcripts from a YouTube video or Short') and distinguishes itself from sibling transcript tools by noting it does not use the two-minute AI transcription fallback. An agent can tell exactly what it gets back and under what source conditions.

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 clear operating context: works for videos of any length when YouTube exposes public captions, honors language selection, and requires confirm=true because it consumes credits. It does not explicitly name when to prefer a sibling (e.g. youtube_video_short_details or a different platform's transcript tool), so routing is left partly to inference.

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

youtube_trending_shortsTrending ShortsA

Fetches approximately 48 currently trending YouTube Shorts (viral/popular short-form videos) per call, returning each short's title, URL, thumbnail, view count (views), like count (likes), comment count, publish date, channel info, keywords, and duration. Each subsequent call returns a fresh batch of different trending shorts. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations cover safety (destructiveHint=false) and open-world/non-idempotent behavior, but the description adds genuinely new context: it consumes paid API credits, needs confirm=true, and does not publish to social platforms. It also aligns with idempotentHint=false by warning each call returns a different batch. Rate limits or failure behavior are not disclosed, keeping it from 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?

Front-loaded with the core fetch behavior and scope, and the enumerated return fields are useful rather than filler. The trailing sentence about 'read-like POST requests' is slightly awkward but justifies its space by pre-empting a publishing concern.

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?

With no output schema, the description responsibly enumerates the returned fields (title, URL, views, likes, comments, etc.) and discloses the credit cost and confirmation requirement. It is close to complete for an agent to call it correctly, though batch/pagination semantics beyond 'fresh batch' are unstated.

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 100%, so both 'account' and 'confirm' are already documented in the schema. The description restates the confirm requirement and clarifies the paid-credit consequence, adding only marginal meaning beyond the schema's own text, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetches'), resource ('currently trending YouTube Shorts'), scope ('approximately 48 per call'), and even what each item contains, so the agent knows this is platform-wide trending discovery. It does not explicitly contrast itself with nearby siblings like youtube_channel_shorts or youtube_search, which is why it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'Each subsequent call returns a fresh batch' hints at repeated polling, and 'requires confirm=true' signals an approval gate. However, there is no explicit statement of when to prefer this over youtube_channel_shorts, youtube_search, or other trending feeds, so alternatives are left to inference.

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

youtube_video_short_detailsVideo/Short DetailsA

Fetches full details for a YouTube video or short, including title, description, thumbnail, view count (views), like count (likes), comment count, publish date, duration, genre, keywords, chapters, collaborators, and available caption tracks (subtitles/captions). isPaidPromotion is true when YouTube marks the video as including paid promotion and false when it does not. Also returns related recommended videos in watchNextVideos and channel info for the uploader. When YouTube exposes its public Most replayed graph, most_replayed contains normalized graph buckets in markers and YouTube's highlighted ranges in ranges. The field is null when the graph is not available. YouTube says the graph may be unavailable when the channel has active strikes, the content is potentially inappropriate, the video is too new or has too few views, or its systems deem the video ineligible for another reason. YouTube does not publish fixed age or view-count thresholds. Age-restricted videos return 403 with message: "This video is age restricted" because Scrape Creators only uses the public logged-out YouTube source. Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	YouTube video or short URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.
`cache_max_age`	No	If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "cached_at" timestamp). Otherwise, scrape a live result (1 credit). [See the Caching page for details.](https://docs.scrapecreators.com/caching)

TDQS

A3.9/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: paid-credit consumption with a required confirm=true, a clarification that the read-like POST does not publish to social platforms (reconciling the readOnlyHint=false), an explicit 403 age-restriction failure mode, and the precise null conditions for most_replayed. This is exactly the behavioral disclosure that annotations alone cannot supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and organized, but the most_replayed passage sprawls across four sentences describing YouTube's internal unavailability reasons and reiterating that no fixed thresholds are published. That detail is genuinely useful for interpreting nulls, yet it is disproportionate for a single nullable field and could be compressed.

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?

With no output schema, the description must carry the return-value burden, and it does: it lists every returned field group, explains boolean semantics (isPaidPromotion), null semantics (most_replayed) and the related-video/channel payloads. An agent has everything needed to call and interpret the response.

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 100%, so url, account, confirm, language, and cache_max_age are already documented in the schema; the description adds no parameter-level syntax or format detail. Baseline 3 applies since the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb+resource ('Fetches full details for a YouTube video or short') and enumerates the returned fields, which distinguishes it from siblings like youtube_transcript or youtube_comments that return narrower slices. It does not explicitly name any sibling as the alternative, but the field enumeration makes the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied rather than stated: the credit and confirm=true notes tell the agent this is a cost-bearing call, and the cache_max_age description supports cost-sensitive reuse. However, there is no explicit 'use this instead of X when Y' routing against the many YouTube siblings (youtube_channel_details, youtube_transcript, youtube_video_sponsors).

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

youtube_video_sponsorsVideo SponsorsA

Experimental endpoint. Checks a YouTube video for the paid-promotion disclosure and infers likely sponsors/promoted brands from the public description, description links, promo-code text, and transcript. YouTube tells us that a video contains paid promotion, but it does not always tell us the sponsor directly, so this endpoint returns suspected sponsors with confidence and evidence. This is inferred, not an official YouTube sponsor field. Feedback welcome: support@scrapecreators.com Potentially consumes paid API credits; requires confirm=true. Read-like POST requests do not publish to social platforms.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	YouTube video or short URL
`account`	No	Named private ScrapeCreators account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific approved credit-consuming research call.
`language`	No	2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc.

TDQS

A3.9/5.0

Behavior4/5

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

Adds substantial context beyond the annotations: it is experimental, consumes paid API credits, requires confirm=true, and explicitly clarifies the 'read-like POST does not publish to social platforms' point that reconciles with readOnlyHint=false. It also discloses that results are inferred, not an official field. Only the absence of detail on latency/pagination keeps it from 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?

Front-loaded with 'Experimental endpoint' and the core purpose, then layering caveats in a sensible order. Slightly long, and the feedback email sentence is filler, but nearly every sentence carries useful information.

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?

With no output schema, the description steps in by describing the return (suspected sponsors with confidence and evidence) and the inference caveat. Combined with annotations covering the safety profile and a fully documented schema, an agent has enough to call this tool correctly.

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 100%, so the schema already documents url, account, confirm, and language. The description only reiterates the confirm=true requirement (adding the cost linkage), leaving account and language unexplained. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (checks a YouTube video for paid-promotion disclosure, infers likely sponsors) and explains the inference mechanism (description, links, promo-code text, transcript). It distinguishes itself from siblings like youtube_transcript and youtube_video_short_details by naming the exact artifact it returns (suspected sponsors with confidence and evidence).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Marks the tool as experimental and states the operating constraint (requires confirm=true, consumes paid credits), which frames when it is worth invoking. However, it never names an alternative tool or an explicit when-not condition, so routing vs youtube_transcript or youtube_video_short_details is left to inference.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

190 tool updatesv2.0.0Oct 2, 2026
- First observedamazon_shop_amazon_shop_page
- First observedapple_music_album
- First observedapple_music_artist
- First observedapple_music_search
- First observedapple_music_track
- First observedbluesky_post
- First observedbluesky_posts
- First observedbluesky_profile
- First observedcreator_tools_find_social_profiles
- First observedcreator_tools_get_age_and_gender
- First observedfacebook_ad_library_ad_details
- First observedfacebook_ad_library_ad_transcript
- First observedfacebook_ad_library_company_ads
- First observedfacebook_ad_library_company_ads_post
- First observedfacebook_ad_library_search
- First observedfacebook_ad_library_search_for_companies
- First observedfacebook_ad_library_search_post
- First observedfacebook_comment_replies
- First observedfacebook_comments
- First observedfacebook_events_event_details
- First observedfacebook_events_events
- First observedfacebook_events_search_events
- First observedfacebook_facebook_group_info
- First observedfacebook_facebook_group_posts
- First observedfacebook_marketplace_marketplace_item
- First observedfacebook_marketplace_marketplace_location_search
- First observedfacebook_marketplace_marketplace_search
- First observedfacebook_post
- First observedfacebook_profile
- First observedfacebook_profile_events
- First observedfacebook_profile_photos
- First observedfacebook_profile_posts
- First observedfacebook_profile_reels
- First observedfacebook_transcript
- First observedgithub_activity
- First observedgithub_contributions
- First observedgithub_followers
- First observedgithub_following
- First observedgithub_pull_requests
- First observedgithub_repositories
- First observedgithub_repository
- First observedgithub_trending_developers
- First observedgithub_trending_repositories
- First observedgithub_user
- First observedgoogle_ad_library_ad_details
- First observedgoogle_ad_library_advertiser_search
- First observedgoogle_ad_library_company_ads
- First observedgoogle_search
- First observedinstagram_basic_profile
- First observedinstagram_comment_replies
- First observedinstagram_comments
- First observedinstagram_embed_html
- First observedinstagram_get_reels_by_audio_id
- First observedinstagram_highlights_details
- First observedinstagram_popular_search
- First observedinstagram_post_reel_info
- First observedinstagram_posts
- First observedinstagram_profile
- First observedinstagram_profile_post_count
- First observedinstagram_reels
- First observedinstagram_search_hashtag_posts
- First observedinstagram_search_instagram
- First observedinstagram_search_instagram_profiles
- First observedinstagram_search_reels
- First observedinstagram_story_highlights
- First observedinstagram_transcript
- First observedinstagram_trending_reels
- First observedinstagram_user_tagged_posts
- First observedkick_clip
- First observedkick_clip_transcript
- First observedkomi_komi_page
- First observedkwai_post
- First observedkwai_profile
- First observedkwai_user_posts
- First observedlinkbio_linkbio_page
- First observedlinkedin_ad_library_ad_details
- First observedlinkedin_ad_library_search_ads
- First observedlinkedin_company_page
- First observedlinkedin_company_posts
- First observedlinkedin_person_profile
- First observedlinkedin_post
- First observedlinkedin_post_transcript
- First observedlinkedin_search_posts
- First observedlinkme_profile
- First observedlinktree_linktree_page
- First observedlist_accounts
- First observedpillar_pillar_page
- First observedpinterest_board
- First observedpinterest_pin
- First observedpinterest_search
- First observedpinterest_user_boards
- First observedreddit_post
- First observedreddit_post_comments
- First observedreddit_post_comments_post
- First observedreddit_post_transcript
- First observedreddit_search
- First observedreddit_subreddit_details
- First observedreddit_subreddit_posts
- First observedreddit_subreddit_search
- First observedresearch_batch
- First observedrumble_channel_videos
- First observedrumble_comments
- First observedrumble_search
- First observedrumble_transcript
- First observedrumble_video
- First observedscrapecreators_get_credit_balance
- First observedscrapecreators_get_daily_usage
- First observedscrapecreators_get_most_used_routes
- First observedscrapecreators_get_request_history
- First observedsnapchat_spotlight_by_link
- First observedsnapchat_spotlight_comments_by_link
- First observedsnapchat_user_profile
- First observedsoundcloud_artist
- First observedsoundcloud_artist_tracks
- First observedsoundcloud_track
- First observedspotify_album
- First observedspotify_artist
- First observedspotify_playlist
- First observedspotify_podcast
- First observedspotify_podcast_episodes
- First observedspotify_search
- First observedspotify_track
- First observedtelegram_channel_details
- First observedtelegram_channel_posts
- First observedtelegram_post_details
- First observedthreads_post
- First observedthreads_posts
- First observedthreads_profile
- First observedthreads_search_by_keyword
- First observedthreads_search_users
- First observedtiktok_ad_library_ad_library_ad
- First observedtiktok_ad_library_ad_library_search
- First observedtiktok_audience_demographics
- First observedtiktok_collection_videos
- First observedtiktok_comment_replies
- First observedtiktok_comments
- First observedtiktok_followers
- First observedtiktok_following
- First observedtiktok_get_popular_creators
- First observedtiktok_get_song_details
- First observedtiktok_live
- First observedtiktok_live_info
- First observedtiktok_profile
- First observedtiktok_profile_region
- First observedtiktok_profile_videos
- First observedtiktok_search_by_hashtag
- First observedtiktok_search_by_keyword
- First observedtiktok_search_suggestions
- First observedtiktok_search_users
- First observedtiktok_shop_product_details
- First observedtiktok_shop_product_reviews
- First observedtiktok_shop_shop_products
- First observedtiktok_shop_shop_search
- First observedtiktok_shop_user_showcase
- First observedtiktok_tiktoks_using_song
- First observedtiktok_top_search
- First observedtiktok_transcript
- First observedtiktok_trending_feed
- First observedtiktok_video_info
- First observedtruth_social_post
- First observedtruth_social_profile
- First observedtruth_social_user_posts
- First observedtwitch_clip
- First observedtwitch_clip_transcript
- First observedtwitch_profile
- First observedtwitch_user_schedule
- First observedtwitch_user_videos
- First observedtwitter_community
- First observedtwitter_community_tweets
- First observedtwitter_profile
- First observedtwitter_transcript
- First observedtwitter_tweet_details
- First observedtwitter_user_tweets
- First observedyoutube_channel_community_posts
- First observedyoutube_channel_details
- First observedyoutube_channel_lives
- First observedyoutube_channel_playlists
- First observedyoutube_channel_shorts
- First observedyoutube_channel_videos
- First observedyoutube_comment_replies
- First observedyoutube_comments
- First observedyoutube_community_post_details
- First observedyoutube_playlist
- First observedyoutube_search
- First observedyoutube_search_by_hashtag
- First observedyoutube_search_typeahead
- First observedyoutube_transcript
- First observedyoutube_trending_shorts
- First observedyoutube_video_short_details
- First observedyoutube_video_sponsors

Deploy Server

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

TDQS

B3.4/5.0

Scored 2026-10-02 22:10 across 190 tools

Disambiguation3/5

Many tools have overlapping purposes, especially within platforms: multiple search endpoints (tiktok_search_by_keyword, tiktok_top_search, tiktok_search_by_hashtag), duplicate GET/POST pairs with identical descriptions (facebook_ad_library_search vs search_post), and near-identical live endpoints (tiktok_live vs tiktok_live_info). Detailed descriptions mitigate some confusion, but the volume and similarity make misselection likely.

Naming Consistency3/5

Most tools follow a snake_case platform_resource_action pattern, but there are inconsistencies: nested prefixes (facebook_facebook_group_info, tiktok_ad_library_ad_library_search), duplicate _post suffixes, and some tools without platform context (list_accounts, research_batch). Still, the convention is generally readable.

Tool Count1/5

190 tools is far beyond the typical 3-15 range and represents an extreme mismatch for a single MCP server. While the domain spans many platforms, the count overwhelms an agent's ability to select appropriately.

Completeness4/5

The surface covers many platforms and operations (profiles, posts, comments, search, transcripts, ad libraries), but there are gaps such as missing Twitter search and Twitter follower/following endpoints. For a read-only scraping API, coverage is extensive though not exhaustive.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

CrackedOAuth
io.github.systemsailab
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Autonomous Agents
1
SupaMarketers Data C
io.github.PuppyChris
30+ marketing data tools for AI agents: keywords, SERP, backlinks, AI visibility, app store & commerce intelligence, Reddit/LinkedIn/Facebook/YouTube research, web search, page extraction, site audit, image & video generation, one-shot marketing apps. Bring your own API key from supamarketers.com — per-tool pricing in Credits.
Research & Data Search Web Scraping
342
superagntOAuth
com.superagnt
AI agent toolkit: live social media data, lead enrichment + email finder, Postgres DB, webhooks.
Social Media Databases Email
1
GoroOAuth
ai.usegoro
62 real-world tools for agents: search, scraping, social, enrichment, image, video, voice.
Search Web Scraping Social Media
1

Related MCP Servers

socialcrawl-mcp
Social Media Search
RidioDevelopment
A
license
A
quality
D
maintenance
Provides AI agents with unified access to 21 social media platforms and 105 endpoints for retrieving profiles, posts, comments, search results, trending content, and analytics without per-platform authentication.
Updated 6 months ago (2026-04-10 13:53 UTC)
4
379 npm
MIT
instagram-mcp
Social Media Communication
osAlhaddad1
F
license
A
quality
C
maintenance
Enables agents to interact with Instagram through 49 tools for direct messages, feed, profiles, search, and persona discovery, with write actions disabled by default until explicitly enabled.
Updated a month ago (2026-08-23 14:21 UTC)
49
-
@sourcevine/mcpofficial
Social Media Research & Data
Sourcevine
A
license
A
quality
B
maintenance
Enables assistants to retrieve public TikTok, Instagram, and YouTube stats, profiles, recent posts, and YouTube transcripts through read-only tools.
Updated 6 days ago (2026-09-29 04:40 UTC)
10
MIT
social-data-mcp
Social Media Web Scraping
mrocker
A
license
Not graded
quality
C
maintenance
Enables AI agents to retrieve X/Twitter profiles and tweets, YouTube video and channel data, and TikTok profile and video stats on a pay-per-result basis without requiring login or platform API keys.
Updated a month ago (2026-08-30 03:03 UTC)
28 npm
MIT

ScrapeCreators MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up ScrapeCreators access

Private API key

Access, pricing and quotas

Provider caching and public-data limits

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

tiktok_profile

tiktok_profile_region

tiktok_audience_demographics

tiktok_collection_videos

tiktok_profile_videos

tiktok_video_info

tiktok_transcript

tiktok_live

tiktok_live_info

tiktok_comments

tiktok_comment_replies

tiktok_following

tiktok_followers

tiktok_search_users

tiktok_search_suggestions

tiktok_search_by_hashtag

tiktok_search_by_keyword

tiktok_top_search

tiktok_get_popular_creators

tiktok_get_song_details

tiktok_tiktoks_using_song

tiktok_trending_feed

tiktok_shop_shop_search

tiktok_shop_shop_products

tiktok_shop_product_details

tiktok_shop_product_reviews

tiktok_shop_user_showcase

instagram_profile

instagram_basic_profile

instagram_posts

instagram_user_tagged_posts

instagram_reels

instagram_post_reel_info

instagram_transcript

instagram_search_instagram

instagram_popular_search

instagram_search_hashtag_posts

instagram_search_instagram_profiles

instagram_search_reels

instagram_get_reels_by_audio_id

instagram_trending_reels

instagram_comments

instagram_comment_replies

instagram_story_highlights

instagram_highlights_details

instagram_profile_post_count

instagram_embed_html

telegram_channel_details

telegram_channel_posts

telegram_post_details

youtube_channel_details

youtube_channel_videos

youtube_channel_playlists

youtube_channel_lives

youtube_channel_community_posts

youtube_channel_shorts

youtube_video_short_details

youtube_transcript

youtube_video_sponsors

youtube_search

youtube_search_typeahead

youtube_search_by_hashtag