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

Annotations already declare destructive=true and idempotent=true, and the description corroborates rather than contradicts them. It adds substantial beyond-annotation detail: all-or-nothing batch atomicity, the validation preconditions (inbound-capable trunk, SMS-enabled group), error behavior naming offending ids, and the re-routing side effect when a number was already routed.

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?

A single dense but front-loaded passage leading with the core action and immediately following with the batch/unassign mechanics. Some validation detail is packed into parentheticals, but every clause carries operational information rather than 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 two-parameter mutation with no output schema, the description covers return values (the trunk or null, affected numbers, count), batch failure semantics, and the disabled-incoming-SMS outcome of unassigning. An agent has everything needed to invoke it correctly.

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 baseline is 3, but the description adds real meaning: the interdependence that every id must belong to the customer account and pass group/trunk validation, and that omitting sms_trunk_id is an unassign rather than an error. The 1..100 range itself is already in the schema.

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 — routing incoming SMS for one or many DIDs to an SMS trunk — plus the scope (single batch call) and the inverse operation (bulk unassign). The 'incoming SMS ... SMS trunk' framing distinguishes it from voice-oriented siblings like assign_did_to_trunk and assign_did_to_capacity_group.

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?

Clear context for both directions of use: assign by providing sms_trunk_id, or unassign by passing null/omitting it, with the consequence (incoming SMS disabled) spelled out. It never explicitly names a sibling alternative to defer to, so it stops short of a 5.

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