Skip to main content
Glama

douyin-favorites-mcp · Douyin Favorites MCP Service

License: MIT

Model Context Protocol (MCP) server for Douyin Favorites / Douyin Collections — reads the Douyin favorites (default favorites), collection folders / albums (e.g., "Learning") of your own account via a logged-in browser session, and exports structured data for AI assistants (Claude / WorkBuddy, etc.) to use.

English: An MCP server that reads your personal Douyin (抖音) favorites and collection folders (favorites/albums) via a logged-in browser session, for use with Claude / WorkBuddy and other MCP clients.

⚠️ Personal authorized use: This tool only reads the favorites data of the currently logged-in account; it does not provide scraping of others' data, CAPTCHA bypass, or signature cracking.

Features

Tool

Description

douyin_login_start

Open headed Chrome to log in to Douyin via QR code (session saved in local profile)

douyin_login_status

Check whether the current session is valid (based on the sessionid cookie)

douyin_logout

Clear the local browser profile

douyin_health_check

Health check

get_self_user_info

Get basic info of the currently logged-in account (nickname/uid/followers/following/likes)

list_collection_videos

Fetch the video list of the default "Favorites" folder

list_collects

List all collection folders (albums): id, name, video count

get_collect_videos

Fetch videos/image-text posts in a specified collection folder (album)

get_video_detail

Get details and interaction data for a single video

Supported content types: videos + image-text posts (long articles); both allow extracting title / author / interaction data / cover / duration.

Related MCP server: video-studio-mcp

How It Works

The Douyin web API has runtime signature protection, so API calls cannot be directly forged. This service uses:

  1. Use Playwright to launch a real Chrome (persistent profile);

  2. Scan the QR code to log in once; the session cookie is saved locally;

  3. Drive the page UI (click the "Favorites" tab, then the "Collection folders" sub-tab), intercept XHR responses;

  4. Parse and return structured data.

Verified endpoints (2026-08):

  • Collection folder list: GET /aweme/v1/web/collects/list/

  • Collection folder contents: GET /aweme/v1/web/collects/video/list/?collects_id=...&cursor=0&count=10

  • All favorites: POST /aweme/v1/web/aweme/listcollection/ (cursor is in the POST body)

Installation

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .
playwright install chromium

Configuration (WorkBuddy / Claude Desktop)

Add to the MCP configuration (e.g., ~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "douyin-favorites": {
      "command": "C:/absolute/path/to/douyin-favorites/.venv/Scripts/python.exe",
      "args": ["-m", "douyin_favorites.server"],
      "env": {
        "DOUYIN_DATA_DIR": "C:/Users/<you>/.douyin-favorites"
      }
    }
  }
}

DOUYIN_DATA_DIR is the location where the browser profile (login state) is stored; do not include it in version control.

First-Time Usage

# 1. 登录(弹出 Chrome,扫码后自动关闭)
python scripts/verify.py

# 2. 或通过 MCP 调用:
#    douyin_login_start
#    douyin_login_status   -> {"logged_in": true}
#    list_collects         -> 列出收藏夹(id + 名称 + 数量)
#    get_collect_videos({"collects_id": "<id>"})

The login state persists across sessions; you usually only need to scan the QR code again every few weeks.

Testing

pytest tests/ -v
python scripts/verify.py          # 端到端验证(需要登录态)
python scripts/verify_collects.py # 列收藏夹 + 第一个收藏夹的视频

Notes and Known Limitations

  • Login state detection is based on session cookies (sessionid / sessionid_ss / sid_guard / sid_tt); do not use DOM elements to determine it (the Douyin homepage shows many author avatars even when not logged in, which would cause false positives).

  • The Douyin homepage never reaches networkidle; use domcontentloaded for all navigation.

  • Pagination on the favorites page is triggered by the real mouse wheel (first mouse.move to the content area, then wheel); window.scrollTo does not work.

  • The "Favorites" tab must be triggered by clicking; the ?showTab=favorite URL parameter alone has no effect.

  • get_video_detail may be temporarily unavailable because Douyin has revamped its detail API.

Disclaimer

This project is for personal learning, research, and data organization only. By using this tool, you confirm that:

  • You only access data from Douyin accounts over which you have full access rights;

  • You will not use this tool for bulk scraping, data resale, engagement boosting, or other illegal/non-compliant activities;

  • You understand that Douyin's APIs may change at any time, causing the tool to become temporarily non-functional.

Any consequences arising from violation of the above terms or applicable laws and regulations shall be borne by the user.

License

MIT

Available Tools

9 tools
douyin_health_checkA

Return login status and profile health for diagnostics.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. "Return... for diagnostics" implies a non-mutating read check, and the empty schema confirms no arguments, but it says nothing about auth prerequisites, rate limits, side effects, or what errors mean for a health check.

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?

A single front-loaded sentence with zero waste. The verb, the returned data, and the intent all appear in one pass.

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?

There is no output schema and no annotations, so the description is the only source of information about return values. It names "login status" and "profile health" but leaves the concrete shape and meaning of "profile health" undefined, which is a real gap for a diagnostics 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?

The tool takes zero parameters, so per the baseline there are no parameter semantics to document. The empty schema is self-explanatory and the description adds nothing misleading.

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 clear verb (Return) and resource (login status and profile health) with an explicit purpose (for diagnostics). It does not, however, distinguish itself from the sibling douyin_login_status, which plausibly covers overlapping territory, so an agent must 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?

"For diagnostics" gives an implied context for use, which is better than nothing. But there is no explicit when-to-use statement, no when-not, and no pointer to the alternative douyin_login_status, so routing between the two 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.

douyin_login_startA

Open a headed Chrome window for the user to scan QR code and login to Douyin.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose important traits: a headed (visible) Chrome window is launched and human QR-scan interaction is required. It omits whether the call blocks until login completes, what happens if a session already exists, and any timeout/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?

A single front-loaded sentence that states the mechanism, the user action, and the target service with no filler. Nothing redundant or buried.

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 zero-parameter trigger the description covers the core action and the human-in-the-loop requirement, but with no annotations, no output schema, and no mention of how login success is confirmed (the role of douyin_login_status), it is not fully complete for the flow.

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 per the baseline there is nothing for the description to disambiguate. No parameter-level detail is missing.

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 action (opens a headed Chrome window to authenticate to Douyin) and makes the mechanism concrete (QR scan). It does not explicitly distinguish itself from the sibling douyin_login_status, 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: the agent can infer this is the entry point for authenticating when not logged in. However, it never says when to call it versus douyin_login_status (i.e., that status should be polled after this call) and states no prerequisites such as 'requires a user present at the machine'.

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

douyin_login_statusB

Check whether the stored Douyin browser session is still valid.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that it checks a stored session, implying a read operation, but does not state return format, side effects, permissions, 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.

Conciseness5/5

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

A single, front-loaded sentence with no wasted words. It is appropriately sized for a simple status-check tool.

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?

The description covers the core purpose but lacks detail on return values and has no output schema or annotations to compensate. For a simple check tool it is minimally adequate, but an agent still lacks information about what the result looks like.

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 document. The baseline for a parameterless tool is 4.

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 ('Check') and resource ('stored Douyin browser session is still valid'). It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as douyin_health_check or douyin_login_start.

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?

Provides no explicit guidance on when to use this tool versus alternatives. It does not mention preconditions, when-not to use it, or name related siblings like douyin_login_start or douyin_logout.

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

douyin_logoutA

Clear the stored Douyin browser profile and force re-login next time.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait — the stored profile is destroyed and re-login is forced — which is the most important side effect. However, it omits whether the action is reversible, whether other active sessions are affected, or any 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.

Conciseness5/5

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

One sentence, front-loaded with the action and its effect, with no wasted words.

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, no-output-schema tool, the description covers the action and its main consequence adequately. Only minor gaps remain, such as error behavior or what happens if no profile is stored.

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 is nothing for the description to disambiguate; baseline 4 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 ('Clear') and resource ('stored Douyin browser profile'), plus the consequence ('force re-login next time'). It is clearly distinguishable from the login/status siblings, though it does not explicitly 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?

Implies the use case (clearing session state so the next call requires login), but gives no explicit when-to-use guidance, prerequisites, or named alternatives among the douyin_login_* siblings.

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

get_collect_videosB

List videos inside a specific Douyin collection folder by collects_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax videos to return
collects_idYesCollection folder id from list_collects

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden. It implies a read of a collection's contents but says nothing about pagination, default/maximum result behavior, auth requirements, or what happens with an invalid collects_id.

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?

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity is also what leaves the sibling-ambiguity and behavioral gaps unaddressed.

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 simple two-parameter list tool with full schema coverage and no output schema, the description is minimally adequate. The main omission is disambiguation from the near-identically named sibling list_collection_videos, which an agent needs to route 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 both parameters (limit, collects_id) are already documented in the schema; the description only restates collects_id as the key. Baseline 3 applies since it adds no syntax, format, or edge-case detail 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?

The description gives a specific verb ('List') and resource ('videos inside a specific Douyin collection folder') and names the keying field (collects_id). It is clear on its own, but it does not distinguish itself from the very similar sibling 'list_collection_videos', leaving the agent to guess which one applies when.

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: it lists videos scoped to a collection, and the schema note 'from list_collects' hints at a prerequisite. There is no explicit when-to-use, when-not-to-use, or naming of alternative tools such as list_collection_videos or list_collects.

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

get_self_user_infoB

Get basic info of the currently logged-in Douyin account.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden. 'Get' implies a read-only operation, but the description does not state auth/session requirements, rate limits, or what 'basic info' actually covers, leaving meaningful gaps for a no-annotation tool.

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?

One short, front-loaded sentence with the subject (logged-in Douyin account) stated before any qualifier. No wasted words.

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 zero-parameter read tool this is nearly complete, but with no output schema the agent has no idea which fields 'basic info' returns. A brief enumeration of the returned fields would close the remaining 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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to clarify or obscure.

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 ('Get') and resource ('basic info of the currently logged-in Douyin account'), which is enough to separate it from the login/logout/video/collection siblings. It does not explicitly name a sibling, so it falls just 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?

'Currently logged-in account' implies that a login session is a prerequisite, which is useful implied usage guidance. However, there is no explicit statement of when to call this versus douyin_login_status or the other retrieval tools, and no exclusions.

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

get_video_detailB

Get detailed metadata and stats for a Douyin video by aweme_id or share_url.

ParametersJSON Schema
NameRequiredDescriptionDefault
aweme_idNoDouyin aweme_id
share_urlNoDouyin share URL

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention authentication requirements, rate limits, error behavior, or whether this is strictly a read-only operation, leaving key behavioral traits unstated.

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 a single, front-loaded sentence with no wasted words. It efficiently conveys the operation and the input options.

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 two-parameter read tool with no output schema, the description covers the core purpose and return type. However, it omits whether authentication is needed and does not clarify that at least one identifier must be supplied, despite neither being marked required 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 description coverage is 100%, so the two parameters are already documented in the schema. The description repeats that either aweme_id or share_url can be used but adds no format details or selection guidance beyond what the schema provides, making a 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 ('Get') and resource ('detailed metadata and stats for a Douyin video') with the identifying inputs. It is clear, but it does not explicitly distinguish itself from sibling tools, so it falls just short of the top score.

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 guidance is given about when to use this tool versus alternatives, nor are there prerequisites or exclusions. The description only states what it retrieves, not when it is appropriate.

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

list_collection_videosC

List videos from the default Douyin 'favorite' collection.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax videos to return
cursorNoPagination cursor from previous response

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations present, the description carries the full behavioral burden but discloses almost nothing: no read-only confirmation, no authentication/login prerequisite (notable given the douyin_login_start/logout siblings), no pagination or rate-limit behavior. 'List' weakly implies a safe read, but that is inference, not 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?

A single efficient sentence with the resource and scope front-loaded and zero filler. It is appropriately sized, though the brevity comes at the cost of the missing usage and behavioral detail noted elsewhere.

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?

This is a low-complexity, zero-required-parameter read tool with a fully documented schema and no output schema, so the description need not explain return values. Still, given the dense sibling set and absent annotations, the lack of any authentication or collection-scoping note leaves a modest 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%: limit and cursor are both documented in the schema, so the description is not required to explain them. It adds no syntax or default-value 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 (List) and resource (videos) and even scopes it to the default Douyin 'favorite' collection, which tells an agent this is the fixed favorite collection rather than an arbitrary one. However, it does not explicitly name or distinguish itself from the closely related siblings list_collects and get_collect_videos, leaving the agent to 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 Guidelines2/5

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

There is no explicit when-to-use guidance, no exclusions, and no mention of the alternative get_collect_videos for non-default or specified collections. The only implicit signal is 'default ... favorite collection', which a careful agent could use to route, but nothing is stated.

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

list_collectsA

List the logged-in user's Douyin collection folders (收藏夹/专辑), with id, name and video count.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden, and it only partially does so: it implies an authentication requirement ('logged-in user's') and that folders are returned, but says nothing about pagination, ordering, failure modes when unauthenticated, or whether private/hidden collections are included.

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?

A single front-loaded sentence with no filler, covering the verb, scope, resource, and returned fields in one pass.

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 parameters and no output schema, the description usefully enumerates the returned fields (id, name, video count) so an agent knows what to expect. The main residual gap is behavioral detail such as auth failure and result ordering, which is acceptable but leaves a small hole.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for and it correctly avoids inventing parameter detail.

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 (List) and resource (Douyin collection folders / 收藏夹/专辑) scoped to the logged-in user, which distinguishes it from the video-oriented siblings list_collection_videos and get_collect_videos. The parenthetical gloss and the listed return fields make the resource unambiguous, 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 guidance, no condition selecting this tool over list_collection_videos or get_collect_videos, and no prerequisites stated. Usage is only implied by the resource name.

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.

  1. 9 tool updatesv0.1.0
    • First observeddouyin_health_check
    • First observeddouyin_login_start
    • First observeddouyin_login_status
    • First observeddouyin_logout
    • First observedget_collect_videos
    • First observedget_self_user_info
    • First observedget_video_detail
    • First observedlist_collection_videos
    • First observedlist_collects

TDQS

B3.4/5.0

Scored across 9 tools

Disambiguation4/5

Most tools target distinct actions (login, logout, list, get detail), but douyin_login_status and douyin_health_check substantially overlap since health_check also reports login status. The rest are clearly separable.

Naming Consistency3/5

Four tools use a douyin_ prefix while five use bare verb_noun, and there is confusing terminology drift between 'collection'/'collect' (list_collects, get_collect_videos). Readable but not a single consistent pattern.

Tool Count5/5

Nine tools is well-scoped for a login-plus-collections server, with each tool earning its place and no bloat.

Completeness3/5

The surface is essentially read-only for a 'favorites' server: no add/remove-favorite, save-to-collection, or search operations, so agents cannot actually manage favorites as the name implies. Core listing and detail reads are covered.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers