direct_attach_callouts

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

With no annotations, the description carries the burden. It discloses that this is a WRITE operation, requires allow_write=true to affect the live cabinet, and 'May re-moderate' as a side effect. This is valuable behavioral context beyond the schema. However, it does not clarify whether the operation replaces or appends to existing callouts, nor does it mention permissions or rate limits, so it is not fully comprehensive.

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, dense sentence that front-loads the action ('WRITE:') and packs essential information: operation, required parameters, source of values, safety flag, and side effect. Every word adds value, with no filler or repetition of schema details.

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?

The tool has 6 parameters, no output schema, and no annotations. The description covers the core workflow, ID sources, and a side effect, but omits important context such as whether the attach operation replaces existing callouts, what the return value is, and how dry_run/moderate_after behave. It is minimally viable but leaves gaps for a tool of this complexity.

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 33% (only project and allow_write have descriptions). The tool description adds meaning to the required parameters: ad_ids are for TextAds and extension_ids are 'from add_callouts/list', which is crucial. It also reinforces allow_write. However, it does not explain dry_run or moderate_after semantics beyond the schema, leaving gaps for some of the six parameters.

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 clearly states a specific action: 'ads.update TextAd CalloutSetting AdExtensionIds' – attaching callout extensions to TextAd via ad_ids and extension_ids. It distinguishes itself from siblings like direct_add_callouts (creating callouts) and direct_attach_video_extension (attaching video) by specifying 'CalloutSetting'. The resource (TextAd) and operation (update) are 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 provides clear usage context: 'Pass ad_ids + extension_ids (from add_callouts/list)' implies a prerequisite workflow (create/list callouts first, then attach). 'allow_write=true' is a mandatory condition for mutation. It does not explicitly name alternatives, but the 'WRITE:' prefix and specific CalloutSetting make the intended use distinct from read/list tools and from video extension attachments.

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