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

Annotations only declare it is a non-destructive, non-idempotent write; the description goes well beyond that by spelling out the return object, both status values, the HTTP 409 'prerequisite_not_met' failure mode with concrete examples (offer/primary feed must exist), and how nextStepType is used. It also documents the project_id inference behavior and the recovery path when project_id is needed.

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 ads-vs-marketplaces distinction are front-loaded, and nearly every clause carries operative detail (statuses, error semantics, ID chaining). The single dense paragraph with nested parentheses makes it harder to scan than a short bulleted layout would, which is the only real cost.

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 supplies the return shape itself and maps integrationId to the ad_id used by get_ad, configure_ad_step and other ads tools, so the agent knows how to continue. Prerequisite failure handling and the optional-parameter defaults are all covered for a 5-parameter mutation tool.

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?

Adds real meaning beyond the 80%-covered schema: channel_code is pinned to channelCode from list_ad_channels, definition_code only when multiple definitions exist (from get_ad_channel definitions[].definitionCode), multichannel_code only when the channel offers one, name is explicitly optional and non-unique (set_ad_name can change it), and project_id's inference rule is explained though the schema leaves it bare.

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 ('Create a new ad for a project') and ties the input to a named source tool ('channels in list_ad_channels'). It also sharply distinguishes ads from marketplaces ('product-listing channels ... not marketplaces'), which resolves the create_ad vs create_marketplace ambiguity in the sibling list.

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 an explicit trigger ('when the user asks to add an ad channel for their products') and an explicit exclusion (not marketplaces, no order sync). It routes the agent onward for follow-up steps (configure_ad_step with nextStepType, list_projects when project_id is required) rather than leaving flow inference to the agent.

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