# MCP tools

Canonical URL: https://docs.viralspy.com/docs/mcp/tools



## Content tools [#content-tools]

| Tool                              | Use it for                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| `viralspy_search_videos`          | Filter classified videos by query, ad, hook, viral hook, media, region, and language. |
| `viralspy_get_video`              | Fetch a video by immutable aweme ID.                                                  |
| `viralspy_find_similar_hooks`     | Find semantically similar opening hooks from a strong seed.                           |
| `viralspy_list_feed`              | Browse breakout, early-breakout, trending, or newest rankings.                        |
| `viralspy_search_creators`        | Discover creators and their immutable UIDs.                                           |
| `viralspy_get_creator`            | Fetch by UID; handle is a mutable discovery fallback.                                 |
| `viralspy_list_creator_videos`    | Inspect a creator's videos or ads using UID.                                          |
| `viralspy_search_advertisers`     | Discover canonical advertiser entities.                                               |
| `viralspy_get_advertiser`         | Fetch by canonical advertiser UUID.                                                   |
| `viralspy_list_advertiser_videos` | Inspect videos assigned to that canonical entity.                                     |
| `viralspy_list_trends`            | Browse current trend reports.                                                         |
| `viralspy_get_trend`              | Fetch one report and its examples.                                                    |

All content tools require `content:read` and count toward fair-use protection, not the monthly analyst allowance.

## Usage and analyst tools [#usage-and-analyst-tools]

`viralspy_get_usage` returns remaining monthly analyst requests and the current search fair-use policy.

`viralspy_analyze` asks the ViralSpy analyst a high-level question. It requires `agent:request` and an `idempotency_key`. Generate a UUID, then reuse it for an identical retry. The server permits two concurrent requests per organisation and returns existing status/result for a duplicate.

```text
Use viralspy_analyze to compare the evidence you found for three advertisers.
Do not use it merely to fetch a record that a primitive read tool can return.
```

Tool results include a short text summary and validated `structuredContent`, allowing clients to reason over stable JSON without scraping prose.