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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds the crucial operational context: this spends money, requires an owner-approved confirmation, keys confirmation to the same requestId, and that the change is only real when status is active. It omits what happens on partial failure or how to recover an outcome after the fact, which is a real gap for a non-idempotent spend operation.

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?

Front-loaded and short, but one of its few sentences is a dangling URI reference ("Fields: soclo://tools/...") that conveys nothing to the caller and displaces useful payload guidance. The conditional/status clauses are compressed to near-telegraphic form.

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 10-parameter, destructively-scoped, money-spending tool with no output schema, the description covers the confirmation guarantees but not the domain inputs (which campaign/ad set, absolute vs multiplier budget, currency guards) nor how to obtain the approved preview values it references. An agent could invoke it correctly on the happy path but is likely to guess at payload semantics.

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 60%, and the description only adds meaning for `confirm` and `requestId` (reuse for confirmation and recovery). The nested payload - budgetValue, budgetValueType, timeStart/timeEnd, campaignId vs adSetId - and the expectedBudget* guard parameters carry no explanation in the description, and the `soclo://tools/...` pointer does not help an agent that cannot dereference it.

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?

"Schedule a budget increase" gives a clear verb + effect, and the tool name conveys the high-demand-period resource. It does not distinguish the tool from the read counterpart (soclo_ads_list_high_demand_periods) or explain what a 'high demand period' is (date-range budget boost vs. permanent budget change), so an agent must infer the semantics.

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 description spells out the required two-phase flow: preview first, then owner-approved `confirm:true` with the same `requestId`, and only treat the result as live once status is `active`. That is concrete when-to-use guidance not available from the annotations. It stops short of naming the preview/status sibling tools an agent should call, leaving the routing implicit.

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