Assign an ad account to a client and set whether Advernue manages it

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), it discloses the important trait that nothing is sent without confirm: true and that there is no server-side dry run — a genuine behavioral fact the annotations do not convey. It stops short of describing permission requirements or reversibility of the assignment.

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?

Two sentences, front-loaded with the action, then the critical safety constraint and endpoint. No filler and nothing buried.

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 write tool with no output schema but with a confirm-gated preview flow documented in the schema, this covers the essentials an agent needs to call it safely. Missing only permission/error context and clarification of the untouched body fields.

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 50%: confirm and idempotencyKey are already documented in-schema, while id, body.clientId and body.managed are bare. The description maps 'clientId' to 'client' and 'managed' to the managed flag, adding marginal meaning, but says nothing about what id refers to or any constraints on the nested body.

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 ('Assign an ad account to a client') plus the second effect ('set whether Advernue manages it') and even gives the PATCH endpoint. It is clearly distinguishable from adAccounts_list/get/sync siblings, though it never names them explicitly.

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 gives a gating condition (must pass confirm: true) which is operational guidance, but it offers no when-to-use vs when-not guidance relative to siblings like adAccounts_sync or adAccounts_get. Usage is implied from the verb rather than spelled out.

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