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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: the request is free, side-effect-free with respect to the number ('This does not delete the number'), and returns state plus code/expires_at once ready. It also discloses a capability limit ('Widely cannot issue a STAC yet') that the annotations cannot express.

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?

Purpose is front-loaded in the first sentence, and the short follow-on sentences each carry a distinct fact (omission rule, return shape, cost, STAC limit, non-destructive). Slightly choppy phrasing in 'The result includes state, and the code with expires_at when state is ready' is the only friction; there is no 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?

With no output schema, the description does the work of describing the return values (state, code, expires_at) and covers cost and the STAC gap. Missing pieces are modest: which states exist and what triggers the transition to 'ready' are not spelled out, but an agent has enough to call it and interpret the result.

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%: e164 is documented in-schema, and the description usefully restates its optional-when-single-number behavior rather than adding new syntax. For code_type, the schema is bare but the description effectively narrows the enum by stating STAC cannot be issued yet, which is meaningful but only partial coverage of the second parameter. Baseline 3 is appropriate.

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 (request/read the free PAC for a UK number on this Widely account) plus the customer-facing goal (moving the number to another provider). An agent can tell this apart from account-level or number-management tools 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 the motivating scenario ('so the customer can move it to another provider') and an invocation rule for the optional number ('leave the number out when the account has one eligible number'). However, it never distinguishes itself from the crowded porting family in the sibling list (get_port, port_requirements, quote_port, start_port, submit_port), so the agent must guess where this fits in that workflow.

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