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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the data source limitation (Vendwiser-issued AWBs only) and the supported environment (Demo shop sample data). It does not cover authentication, rate limits, or error behavior, keeping it from a 5.

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 description is front-loaded with the core operation ('One AWB by its reservation id') and packs returned fields, scope limitations, and environment support into a compact block. Every sentence carries useful information, though the bracketed '[Orders]' tag and demo shop note are minor context rather than essential selection criteria.

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 rich annotations and an output schema, the description does not need to explain return values and correctly focuses on selection and invocation constraints. It covers the required identifier's origin and the critical scope limitation, but it leaves the account parameter behavior entirely to the schema and does not clarify the handoff from orders_issue_awb.

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 50%: the optional account parameter has a schema description, but reservation_id has none. The description compensates partly by explaining where reservation_id comes from ('returned when the AWB was issued through Vendwiser'), but it adds no format or additional meaning for the account parameter. This is baseline adequate for the covered parameter but leaves a gap.

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 ('One AWB by its reservation id'), lists the key returned fields, and clarifies the scope: only AWBs issued through Vendwiser can be read via the marketplace API. This clearly distinguishes it from sibling write tools such as orders_issue_awb and from external AWBs that are out of 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?

It gives a clear when-to-use signal (reservation id returned when the AWB was issued through Vendwiser) and an explicit when-not condition (AWBs made in Seller Center or another system cannot be read). However, it does not name a specific alternative tool for issuing an AWB or explain the workflow relationship with orders_issue_awb explicitly.

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