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

Annotations already flag destructiveHint and idempotentHint, yet the description adds genuinely non-redundant behaviour: the hard-vs-soft delete decision rule, the fact that history grouping is preserved, the soft_deleted response flag, and the dual 404 case for unknown ids and other-workspace campaigns. This is exactly the extra context annotations cannot carry.

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?

Four sentences, all front-loaded with the core action first, then the delete-mode semantics, then error behaviour. Every sentence contributes; only "Either way the campaign stops appearing anywhere" is mildly restating an implication.

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?

With no output schema, the description usefully explains the soft_deleted flag and error responses, which is what an agent needs to interpret results. The one real gap is parameter guidance for the five inputs, particularly the required idempotency_key, which is never addressed.

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 only 40% across five parameters, and the description adds almost nothing: it never mentions idempotency_key, brand_id, workspace_id, or the query override object. "404 for unknown ids" loosely implies the id parameter but provides no format or constraint guidance, so the description fails to compensate for the coverage gap.

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 ("Delete a content campaign") and immediately scopes the operation against the rest of the catalogue by naming the campaign object, which is distinct from sibling delete tools like aidelly_delete_draft or aidelly_delete_content_automation. An agent can identify the target entity without opening the 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 clear conditions under which it should be relied on: campaigns with no scheduled/published posts are hard-deleted, those with history are soft-deleted, and unknown or cross-workspace ids return 404. It does not name an alternative tool, but no sibling performs campaign deletion, so the omission is minor.

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