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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description adds the useful constraint that confirm:true requires prior owner approval and the same requestId for recovery. However, it never says what is destroyed or replaced (are existing snippets overwritten, appended, or matched by assetResourceName?), and "Claim live only when status is active" is opaque and unmotivated for this resource.

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?

Short and front-loaded, but one of three sentences is a pointer to a soclo:// URI that conveys no information, and the spending/deletion sentence is generic template text that does not earn its place on a snippet-update tool.

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 destructive, open-world mutation with 10 parameters, nested objects and no output schema, the description should say what a snippet update actually does to existing assets and how to verify the result. It supplies neither, leaving the agent unable to predict side effects from the definition alone.

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 only 60% across 10 parameters with a nested payload, and the description compensates for none of it: no explanation of payload.updates, assetResourceName, platform, parameters, or why currency/budget-type fields exist on a snippet tool. The requestId/confirm semantics it does mention are already spelled out in the schema descriptions.

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 states a verb+resource ("Update account snippets") but stops there — it never explains that these are structured snippet assets (header + 3-10 values) attached to a customer account, nor how this differs from soclo_ads_add_account_structured_snippets, soclo_ads_list_account_structured_snippets or soclo_ads_remove_account_structured_snippet in the sibling set. The trailing "Fields: soclo://tools/..." line is a self-reference, not a scope statement.

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 only usage guidance is a hedge about spending/deletion preview and owner-approved confirm:true, which is boilerplate that does not tell an agent when to pick update over add/remove/list. Worse, updating snippets is not a spending operation, so the cue is partially misleading about what this tool actually costs or destroys.

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