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

Beyond the annotations, it discloses concrete effects ('customer.on_hold set; o2c_confirm_order refuses while held') and clarifies non-effects ('Already-confirmed orders are not touched — fulfil and bill them as agreed'). This tells the agent exactly what the mutation does and does not affect.

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?

It is front-loaded with the core action, then explains the key behavioral constraints and effects in a tight sequence. Every sentence contributes useful context: what a hold is, what it does not touch, when to use it, and its effects.

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 two-parameter mutation tool with annotations and full schema coverage, the description covers purpose, usage conditions, side effects, and exclusions. No output schema exists, but the description explains the observable consequence (confirmations are refused while held), which is sufficient.

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 100%, so parameter meanings are already documented. The description reinforces that 'reason' is shown when the hold blocks something, but adds little beyond the schema for customer_id or reason.

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 specific verb and resource: 'Put a customer on credit hold.' It also distinguishes the hold from credit-limit logic ('A hold outranks the limit') and from existing order handling ('Already-confirmed orders are not touched'), making the scope clear without opening sibling schemas.

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?

It gives clear conditions and examples for when to use the tool: 'a bounced check, a dispute turning sour, news about the customer.' It also implicitly limits use to taking on NEW exposure, but it does not explicitly name core_release_customer as the undo path or state when not to use it.

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