tiktok_get_spark_ads

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that the tool has a 'conservative fallback' when Spark-specific fields are unsupported, which is a useful behavioral trait. However, 'conservative fallback' is undefined—an agent cannot tell whether that means empty results, partial fields, or an error—so the transparency is only partial.

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 a single sentence, front-loaded with the main action, and contains no filler or redundant restatement of the tool name. The fallback behavior is included without bloating the text.

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?

Given no output schema and no annotations, the description leaves too much unspecified: the response shape, the exact fallback behavior, how the optional filters interact, and what 'Spark Ads context' actually contains. An agent trying to call this tool correctly would need to infer or experiment to understand the return value and edge cases.

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 75%, but the description itself adds no parameter-specific meaning. It never mentions advertiserId, adIds, adgroupId, or limit, and the 'ad fields' phrase is too vague to clarify which parameters control the returned context. The one undocumented parameter (limit) is not compensated for by the description.

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 specific resource ('Spark Ads context') and action ('Return'), and adds the qualifier 'from ad fields when available.' It is not a tautology and is more specific than many sibling names, but it does not explicitly distinguish itself from the closely related sibling tiktok_get_spark_organic_joins.

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?

There is no guidance about when to use this tool versus its many siblings, nor any mention of prerequisites or the conditions under which the fallback should be expected. The phrase 'when available' refers to data availability, not to user decision-making, so it does not help an agent choose between alternatives.

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