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

Annotations say readOnly=false, destructive=false, openWorld=true, and the description adds genuinely new behavioral context beyond that: the call produces a draft only, does not constitute legal authorization, and the remaining carrier details plus signed authorization and phone bill are completed by the owner in Calls & messages (/app/calls). That handoff detail is exactly what an agent needs and is not in the annotations.

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?

The permission gate and sign-in requirement are front-loaded, and every clause carries operational meaning — no filler. A few sentences are compound and could be split for readability, but nothing is redundant.

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 single-parameter mutating tool with no output schema, the definition covers auth, plan prerequisite, what is and is not created, where the workflow continues, which data must never be collected in chat, and the service-continuity caveat. Almost nothing an agent needs before invoking it 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?

There is one parameter, 'number', with 0% schema description coverage, so the description must carry the burden and it does not. It never says the parameter is the phone number being ported, whether it must be E.164 or otherwise formatted, or whether it must be the owner's own number versus a business line.

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: 'Create a draft transfer,' and immediately scopes it by saying it 'does not submit the legal authorization,' which separates it from a full port submission. It could be sharper about the relationship to activate_phone_number, but the draft-versus-final distinction is unambiguous.

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?

Explicit preconditions ('Owners only (needs sign-in)', 'An active plan is required') and an explicit trigger condition ('only when the owner explicitly asks'). It also names exclusions and prohibitions: never collect a carrier PIN, phone bill, bank details or signature in chat, and keep current service until carrier confirmation.

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