bilibili_save_videos

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, but the description adds meaningful behavior beyond that: it deduplicates before adding, reads back to verify, deletes nothing, and treats unconfirmed old tasks as verify-only. It does not describe rate limits or what the verification read-back returns, which keeps 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.

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

Four short clauses, front-loaded with the primary action, then the default target, then the safety sequence (dedupe, add, verify, no deletion), then the preview and retry qualifiers. Every sentence adds information with no repetition.

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?

For a 4-parameter mutation tool with no output schema, the definition covers the mutation semantics, the safety guarantees, and the dry-run mode. Gaps remain around what a successful save returns and how target/folder selection interacts with the configured default, which an agent would need.

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 description coverage is 0%, so the description must carry parameter meaning, and it largely does: preview=true is explained as check-only, the default configured target explains why targets is optional, and the 'don't blindly resend' clause maps to retry_unconfirmed. It never explains the videos array limits or the watch_later/favorite target kinds explicitly, leaving some schema detail unstated.

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 names a concrete verb (add to watch-later / favorites) and the resource (videos), and scopes it to 'final recommendation or explicitly user-requested' items. It does not explicitly name a sibling to contrast with, even though bilibili_get_save_receipt and bilibili_list_favorite_folders sit adjacent to it, so it falls one step short of full differentiation.

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?

The usage context is clear: use it for final recommendations or explicit user requests, use preview=true to only check, and for unconfirmed legacy tasks default to verification rather than resending. What's missing is a pointer to the sibling tools (e.g. get_save_receipt for reading back receipts, list_favorite_folders for folder IDs), so the agent must infer alternatives.

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