douyin_parse

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

With only a title annotation, the description carries the disclosure burden and does well: it states no login is required, that output is structured with a fixed field set, that the raw flag yields very long JSON, and that multi-link input is not supported in one call. It omits failure behavior for invalid or private links and does not mention 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.

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

One front-loaded sentence states the capability and enumerates the output fields, followed by two short operational notes. It is dense but every clause carries information; the only cost is that the output enumeration makes the first sentence long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 is genuinely necessary and is done here. Login requirements and batching constraints are also covered, leaving only error/edge-case handling unspecified for a two-parameter, single-purpose parser.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 meaning by emphasizing that target can be a full share blurb containing Chinese text, a bare 19-digit ID, or a sec_uid, which clarifies the accepted input far better than the schema's terse list. It also frames raw as a debugging-only option, reinforcing the schema note.

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

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

The description opens with a specific verb (解析) and enumerates accepted resource forms (分享链接/分享文案/裸作品ID/用户主页链接), then lists the exact fields returned (作品类型、文案、话题、作者、互动数据、无水印播放地址、图集图片、背景音乐). This clearly separates it from siblings such as douyin_download or douyin_user_profile, which act on a parsed result rather than producing it.

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

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

It states an operative precondition ('不需要登录') and gives explicit batching guidance ('批量粘贴多个链接时请逐个调用'), which tells the agent how to handle multi-link input. It does not name an alternative tool or say when to prefer douyin_user_profile for profile-only data, 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.