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

Annotations only cover the safety profile (destructive, idempotent, not readonly); the description goes further with validation rules ('name must be nonblank and unique'), null-clearing semantics ('Null clears description and aliases'), preservation behavior ('Preserves item ID and omitted fields'), and a cascade side effect ('Refreshes active stable-ID prompt labels'). This is unusually rich behavioral disclosure beyond structured fields.

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?

Dense but front-loaded with the core purpose and scope before constraints and side effects. Each clause carries information, though the final 'Returns...' sentence is partly redundant given the output schema exists.

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?

Covers prerequisites, validation, null semantics, cascade effects, preservation behavior, and the non-action exclusion ('Does not launch a Scan'). With an output schema present, return values need only a mention, which is supplied. Nothing an agent needs to call this correctly is missing.

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?

With 40% schema coverage the description compensates well: it defines name constraints (nonblank, unique), the meaning of null for description/aliases, and where to obtain itemId ('from get_scan_config.products'). siteId is covered by the schema itself. Minor gap: no guidance on the aliases array shape beyond null semantics.

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+resource ('Edit a strategy product/service') and explicitly delimits scope: 'separate from business-profile products and tracked entities' and 'on a Site or Topic'. An agent can distinguish this from create_product, remove_product, and business-profile product tools 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?

Gives a concrete prerequisite ('Read get_scan_config.products for definitions and IDs') and an explicit exclusion ('Does not launch a Scan'). It does not spell out when to prefer this over update_site/update_topic, but the domain routing is clear enough to select correctly.

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