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

With annotations present, this still adds substantial context: success preconditions, the non-purchase/reversible nature of the operation, the release semantics of channels_count:0, and the return payload. These behavioral traits are not derivable from the annotations alone. There is only mild tension with destructiveHint=true (the release path), which the description actually explains rather than contradicts.

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 with the purpose, then parameters, preconditions, release semantics, the not-a-purchase clarification, and returns. Every sentence carries distinct information; none is filler.

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 mutation tool with no output schema, the description covers what is mutated, preconditions, reversibility, the alternative purchasing path, and the return payload (DID number, reserved count, pool). Nothing an agent needs to invoke it correctly is missing.

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 100%, so the schema already documents all three parameters and their formats, giving a baseline of 3. The description adds semantic meaning by tying capacity_pool_id and channels_count to the pool's free-channel and country-coverage constraints, going slightly beyond the schema text.

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 ('Reserve dedicated inbound channels for one of the customer's DIDs out of a Capacity Pool') and explicitly distinguishes itself from buy_capacity_channels, which it names. An agent can tell it apart from the assign_did_to_trunk/capacity_group siblings by the 'dedicated channels out of a pool' scope.

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 explicit when-to-use (reserving dedicated channels) and when-not (purchasing, which is buy_capacity_channels), plus the prerequisites for success: country must be covered by the pool, the pool must have free channels, and the DID Group must allow additional channels. It also explains the channels_count:0 release case, which is a distinct usage mode.

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