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

Annotations already declare write, non-destructive, open-world, and non-idempotent behavior. The description adds valuable context beyond that: it creates a tracker, produces no label, incurs no shipping charge, requires your own carrier contract, and uses POST /trackers.

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?

Two tight sentences, front-loaded with WRITE, then the key scope, constraints, side effects, and endpoint. The carrier list reinforces the enum without becoming bloated.

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 write tool with no output schema, the description gives purpose and key constraints but omits what the create call returns and what notification_email does. Those gaps matter for correct invocation, especially the unexplained optional parameter.

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 only 33%. The description reinforces the carrier enum and adds the important restriction that it must be your own carrier contract, but it never explains the optional notification_email parameter, so it only partially compensates for the low schema coverage.

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 action and resource: have shipcloud track/create a tracker for a parcel NOT created with shipcloud, using the carrier's tracking number. It clearly distinguishes this from creating a shipment with a label and from retrieving an existing tracker.

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 clear when-to-use context: parcels not created with shipcloud, only your own carrier contracts, and only dhl/dpd/gls/ups. It does not explicitly name sibling alternatives such as create_shipment_with_label or get_tracker, so it falls short of full alternative routing guidance.

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