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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description only needs to add beyond that. It does add useful context — the AD_IMAGE eligibility caveat and the Performance Max routing — but it never warns about the practical consequence of idempotentHint=false (repeated calls likely create duplicate links) nor about error behavior for mismatched customer/asset.

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?

Front-loaded with the one-line purpose before the Args block, and every arg entry carries information. Minor waste in the trailing "Tools revision: 5c9bea8f." artifact and a Returns section that duplicates the output schema.

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 four-required-parameter mutation with annotations and an output schema, the description covers the decision an agent actually needs to make (which field_type, and when to use a different tool instead). Gaps are minor: duplicate-link behavior and cross-customer/asset validation are unaddressed, but the output schema and annotations absorb the rest.

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 0%, so the description carries the full burden and does so well: customer_id format ("numbers only, no hyphens"), campaign_id purpose, asset_resource_name provenance ("from create_*_asset tools"), and critically the full enumerated list of field_type values, which the schema leaves as an unconstrained string. It stops short of explaining what a resource name looks like syntactically.

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?

States a specific verb and resource ("links an existing asset to a campaign") and immediately distinguishes itself from the create_* family by requiring a pre-existing asset. The name plus the description leaves no ambiguity versus siblings like link_asset_to_ad_group, link_assets_to_customer, or add_assets_to_asset_group.

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?

Gives a clear workflow precondition ("After creating an asset... use this tool to attach it") and names an explicit alternative route for the Performance Max case (add_assets_to_asset_group). It does not spell out how it differs from link_asset_to_ad_group or link_assets_to_customer, so the agent still has to infer the level-selection logic from names alone.

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