Extend a post’s Spark-Ads authorization

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

Annotations give readOnlyHint:false and destructiveHint:false, but the description adds rich behavioral detail: the ADD-not-SET semantics with TikTok's own example, the allowed values (7/30/60/180/365), the requirement that ad authorization must already be active, and the non-obvious return behavior ('The reply reads the new window back, because TikTok's own response body is empty'). It also flags the account authorization need. This goes far beyond annotations, fully disclosing side effects and constraints.

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?

The description is longer than average but every sentence carries critical information: purpose, add-not-set warning, allowed values, prerequisite, and return behavior. It is front-loaded with the primary action before clarifying nuances. The use of caps and dashes emphasizes key points without becoming rambling. Slightly dense but efficient for the complexity it covers.

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 2-parameter mutation tool with no output schema, the description covers everything needed to call it correctly: what it does, how the time period is computed, allowed values, prerequisites (both ad-authorization state and TikTok account auth), and what to expect in the reply. There are no missing pieces; the tool is self-sufficient.

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%: both itemId and authorizationDays have descriptions. The description adds extra semantic depth to authorizationDays by explaining the add-not-set behavior with an example and reiterating allowed values and the default. itemId is straightforward and the description doesn't add more, but the added value on the key parameter justifies a 4 rather than baseline 3.

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 resource: 'Extend how long a post the authorized account owns stays promotable as a Spark Ad' and immediately adds the code-regeneration behavior. It clearly distinguishes from siblings (set_tiktok_post_ad_authorization, get_*, delete_*) by stating it extends an existing authorization, not setting or retrieving. The add-not-set clarification further nails the exact behavior, making it unambiguous.

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 description explicitly states two prerequisites: ad authorization must already be ON (via set_tiktok_post_ad_authorization) and TikTok account authorization is required (referencing tiktok_account_status). It implies this tool is for extending an existing authorization, not initial setup, but does not explicitly list when not to use it or mention alternative extend tools (there are none). Slight gap in explicitly contrasting with set_* but the prerequisite note effectively routes usage.

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