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

Beyond the annotations, the description discloses the credit cost (1 credit per successful call, plan-dependent), warns that retries may charge again, and adds a trust caveat for returned data. This meaningfully extends readOnlyHint/openWorldHint/idempotentHint=false and is consistent with a non-idempotent, billable lookup. It does not cover latency or failure behavior for invalid/expired links.

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?

Three short sentences, front-loaded with the core transformation, then cost, then the trust caveat. Every sentence earns its place; only "actual cost follows your plan" is slightly redundant padding around the cost warning.

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 two-parameter lookup with no output schema, the description states the return value (product ID), the billing model, and a data-trust note, which is nearly everything an agent needs. The only gap is no guidance on what to do next with the resolved ID or how failures surface.

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 100%, so both url and marketplace are already documented in the schema, and the description adds no new syntax, format, or marketplace-behavior detail. Baseline 3 applies because the schema carries the parameter burden.

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?

"Turn a TikTok Shop product link or share link into its product ID" names a specific verb (resolve/convert), the exact input resource (product link or share link) and the exact output (product ID). Among siblings like tiktok_shop_products_detail and tiktok_shop_products_search, this is unambiguously the URL-to-ID converter, so an agent can route to it without opening a schema.

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?

Usage is implied by the input type: you reach for this when you hold a link rather than a product ID. However, the description never states that explicitly, never says what to do with the returned ID next (e.g. hand it to tiktok_shop_products_detail), and gives no exclusions or preconditions.

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