---
title: ToolRouter — Tool Detail
description: Detailed documentation for a ToolRouter tool including skills, parameters, and examples.
url: https://toolrouter.com/tools/similar-movies
---
# Similar Movies

Turn one favorite movie or a small set of seed titles into a ranked shortlist of genuinely similar films. Great for watchlist building, movie-night planning, and agents that need explainable recommendations instead of generic search results.

- **Version:** 0.01
- **Categories:** search, data
- **Workflow:** find_similar → blend_taste

## Skills (2)

### Find Similar (`find_similar`)

Resolve one movie title or TMDb id and return a ranked shortlist of similar films with clear match reasons and alternate seed matches when the title is ambiguous.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | No | Movie title to resolve, such as "Inception" or "The Prestige" |
| `tmdb_id` | number | No | Optional TMDb movie id for an exact seed lookup |
| `year` | number | No | Optional release year to disambiguate the seed title |
| `strategy` | string | No | Ranking source: blended uses both recommendations and similar titles, recommendations uses TMDb recommendations only, similar uses TMDb similar only (blended, recommendations, similar) [default: "blended"] |
| `include_same_collection` | boolean | No | When false, exclude movies from the same TMDb collection or franchise where possible [default: false] |
| `min_vote_average` | number | No | Optional minimum TMDb vote average for returned movies, from 0 to 10 [default: 0] |
| `language` | string | No | Optional TMDb language code for localized titles and overviews, such as en-US or fr-FR [default: "en-US"] |
| `limit` | number | No | Maximum movies to return per page (1-20, default 10) [default: 10] |
| `page` | number | No | Result page number for the ranked shortlist (default 1) [default: 1] |

**Returns:** A resolved seed movie plus a paginated shortlist of similar films with match scores and human-readable reasons

**Examples:**

*Find movies similar to Inception without returning the same franchise:*

```json
{
  "title": "Inception",
  "include_same_collection": false,
  "limit": 8
}
```

*Use recommendation-only ranking for Arrival with a quality floor:*

```json
{
  "title": "Arrival",
  "strategy": "recommendations",
  "min_vote_average": 7,
  "limit": 6
}
```

### Blend Taste (`blend_taste`)

Blend recommendations from multiple seed movies into one ranked shortlist so you can discover films that sit at the intersection of several favorites.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `titles` | array | No | Seed movie titles to blend together, using two to five favorites for the strongest results |
| `tmdb_ids` | array | No | Optional exact TMDb movie ids to use as seeds instead of title resolution |
| `avoid_titles` | array | No | Optional movie titles to exclude from the final shortlist |
| `avoid_tmdb_ids` | array | No | Optional exact TMDb ids to exclude from the final shortlist |
| `include_same_collection` | boolean | No | When false, exclude movies from the same TMDb collection or franchise where possible [default: false] |
| `min_vote_average` | number | No | Optional minimum TMDb vote average for returned movies, from 0 to 10 [default: 0] |
| `language` | string | No | Optional TMDb language code for localized titles and overviews, such as en-US or es-ES [default: "en-US"] |
| `limit` | number | No | Maximum movies to return per page (1-20, default 10) [default: 10] |
| `page` | number | No | Result page number for the ranked shortlist (default 1) [default: 1] |

**Returns:** A blended, paginated shortlist built from multiple seed movies, including matched seeds, excluded titles, and explainable reasons

**Examples:**

*Blend Inception and Arrival into one sci-fi shortlist:*

```json
{
  "titles": [
    "Inception",
    "Arrival"
  ],
  "include_same_collection": false,
  "limit": 8
}
```

*Blend Knives Out, Zodiac, and Gone Girl while excluding Se7en:*

```json
{
  "titles": [
    "Knives Out",
    "Zodiac",
    "Gone Girl"
  ],
  "avoid_titles": [
    "Se7en"
  ],
  "min_vote_average": 7,
  "limit": 10
}
```

## Quick Start

```bash
# Via CLI
TOOLROUTER_API_KEY=tr_live_xxx npx -y toolrouter-mcp call similar-movies find_similar --title Inception --include_same_collection false --limit 8

# Via REST API
curl -H "Authorization: Bearer tr_live_xxx" \
     -d '{"tool":"similar-movies","skill":"find_similar","input":{"title":"Inception","include_same_collection":false,"limit":8}}' \
     https://api.toolrouter.com/v1/tools/call
```

## Frequently Asked Questions

### What is the difference between find_similar and blend_taste?

`find_similar` starts from one seed movie, while `blend_taste` merges recommendations from several seed films into one shortlist. Use the single-seed flow for a straightforward “movies like this” request and the blend flow when the taste brief is really an intersection of two or more favorites.

### Do I need an exact TMDb id before using the tool?

No. You can pass a normal movie title and the tool will resolve the best seed match for you. If a title is ambiguous, the response also includes alternate seed matches so you can see what else it considered.

### Can I avoid sequels or same-franchise recommendations?

Yes. Set `include_same_collection` to `false` to filter out movies from the same TMDb collection where the API exposes that relationship. This is useful when you want adjacent films rather than the obvious sequel list.

### Can I exclude a movie I have already seen from the final shortlist?

Yes. `blend_taste` accepts `avoid_titles` and `avoid_tmdb_ids`, so you can remove obvious or already-watched picks from the results before you review the final ranking.

---

## Get Started with ToolRouter

**Already connected?** Call any tool with `use_tool({ tool, skill, input })`. Browse tools with `discover` or visit https://toolrouter.com/llms-full.txt

**New to ToolRouter?** Connect with one command (no API key needed — auto-provisions on first use):

```bash
# MCP (Claude Code, Codex CLI)
claude mcp add toolrouter -- npx -y toolrouter-mcp

# MCP (Cursor, Windsurf, Cline, VS Code, Gemini CLI, Claude Desktop)
{"mcpServers":{"toolrouter":{"command":"npx","args":["-y","toolrouter-mcp"]}}}

# Claude Chat / Claude Cowork / Claude Mobile — add as a connector:
# Settings → Connectors → Add custom connector → URL: https://api.toolrouter.com/mcp

# ChatGPT — add as an app:
# Settings → Apps → Advanced settings → enable Developer mode → Create app → MCP Server URL: https://api.toolrouter.com/mcp

# CLI (works instantly, no restart needed)
npx -y toolrouter-mcp tools                    # browse all tools
npx -y toolrouter-mcp search "seo"             # search by keyword
npx -y toolrouter-mcp call seo analyze_page --url https://example.com
```

Free tools work immediately. For paid tools, visit https://toolrouter.com/claim to add credits.

All platforms: https://toolrouter.com/connect | Full catalog: https://toolrouter.com/llms-full.txt | Docs: https://toolrouter.com/docs