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

Annotations already establish this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's job is to add context. It does: it explains the adset_params/adgroup_params wire alias, the music_info music_id format constraint (one nonempty ID, <=256 chars), and that source_receipt is required when reverse-engineered source fields are supplied. Auth scope is only loosely hinted at with 'authenticated user'.

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?

Well front-loaded: the core action leads, followed by alias handling, then REQUIRED/OPTIONAL parameter blocks and an EXAMPLE. The REQUIRED/OPTIONAL/EXAMPLE scaffolding is scannable. The music_info paragraph is somewhat niche and dense, but it is relevant rather than filler.

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 17-parameter mutation tool with no output schema and 0% schema coverage, the definition gives the agent the essentials: required vs optional split, the alias mapping, key constraints, and a worked example. What remains thin is the internal shape of the various *_params dicts, though the example partially demonstrates them.

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% across 17 parameters, so the description must carry the load. It adds real value by documenting the name length limit (<=200 chars), the adset/adgroup alias equivalence, and the source_receipt requirement, and the example shows concrete campaign_params/adset_params keys. But most dict and source_* parameters are listed by name only with no format or content guidance, so the compensation is partial.

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 saved template for the authenticated user.' The word 'create' cleanly separates it from siblings like templates_update, templates_delete, templates_get and templates_list without needing to name them. It is clear but does not explicitly route away from templates_reverse_engineer, which also produces templates.

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?

Provides targeted guidance for one case — selecting music via assets_list_music and omitting music_info to defer selection to create preparation — and clarifies that media selections belong on the create request, not the template. However, it never states the general when-to-use vs templates_reverse_engineer or templates_update, leaving the primary routing decision implied.

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