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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds material behavior beyond them: the domain constraint that ads 'have no order sync', the conditional project_id inference ('inferred for a single-project customer; project_id_required otherwise'), and the versionType distinction ('primary marks the default'). These are operational facts an agent cannot derive from the annotations or schema.

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?

Purpose and the pre-create_ad guidance are front-loaded, and the ads-versus-marketplaces clarification is placed early where it matters. The middle sentence inlines a long, dense return-shape enumeration ({channelCode, label, kind, devOnly, ... capabilities:{...}}) that reads as a single run-on block. It is justified by the absence of an output schema, but the formatting costs readability.

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?

With no output schema, the description carries the burden of describing the return value and does so completely, including the nested definitions array, the capabilities sub-object, and the meaning of versionType. Combined with the caller-side prerequisites (list_ad_channels for channel_code, list_projects for project_id), an agent has everything needed to call this correctly on the first attempt.

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 50%: channel_code is documented in the schema, project_id is not. The description compensates by explaining that project_id is optional, when it is inferred, and what to do when it is required (call list_projects). channel_code semantics are largely restated from the schema, so the added value is real but concentrated on the one undocumented parameter.

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+resource: 'Get one ad channel's detail: the integration TYPES it supports and each type's capabilities.' It further separates this tool from its closest siblings by defining what an ad channel is (product-listing channels such as Google Shopping, Meta catalog, Microsoft, price comparison) versus a marketplace, and by contrasting it with list_ad_channels and create_ad. An agent can distinguish it from get_marketplace_channel and list_ad_channels without opening any schema.

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?

It states the exact use case twice: 'Use this to choose the integration type before create_ad' and 'Call this before create_ad to choose the right definitionCode for the channel.' It also names the prerequisite source for the required argument ('channel_code is the channelCode from list_ad_channels') and gives an explicit fallback path ('call list_projects and pass its project_id'). The only mild gap is that it does not explicitly name get_marketplace_channel as the alternative for marketplace-type resources, but it rules them out clearly.

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