draft_sitelinks

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

With no annotations provided, the description carries the full behavioral burden and does so excellently. It discloses the mid-apply failure mode (association raises after the library add landed), that errors surface extension_ids for reconciliation, and the non-idempotency trap that a retry re-runs ALL steps including re-adding extensions. This is precisely the failure/retry context an agent needs.

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 core purpose and data shape are front-loaded, followed by a verification caveat and then the failure/retry detail. Every sentence earns its place and there is no filler; the retry paragraph is dense with parentheticals but contains substantive, necessary information rather than padding.

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-param tool (one being a loosely-typed array), it covers purpose, item shape, a prerequisite, and failure semantics. Gaps remain: no mention of the return value on success, campaign_id semantics are unaddressed, and given sibling confirm_and_apply exists, the description never explains the draft-then-confirm lifecycle or that a draft may require a subsequent confirmation step.

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 compensate. It does document the sitelinks array item shape ([{text, url, description1?, description2?}]), which adds real meaning to that parameter. However, campaign_id receives no semantic help beyond 'integer' in the schema, and the array's additionalProperties: true means the shape relies entirely on this prose.

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?

'Draft sitelinks on a campaign' states a specific verb, resource, and scope, and the bracketed item shape clarifies what is being created. It distinguishes from sibling extension tools (create_callouts, create_structured_snippets) by resource type and from apply/confirm tools by the 'draft' verb, though it never explicitly names a sibling it is not.

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 provides one genuine prerequisite ('Copy claims must be site-verified') that an agent must check before calling. However, it gives no explicit when-to-use vs alternatives guidance and no exclusion conditions, leaving the decision between this and related extension tools (create_callouts, remove_extension) to inference.

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