VendorDirectFulfillmentShippingV1_getPackingSlip

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

With no annotations, the description carries the burden and does add useful contextual signals: it is a catalog entry, it runs in the user's Kuudo deployment rather than in the current environment, and it reads/returns rather than mutates. It does not disclose response shape, error behavior, or authorization needs, but for a read-only retrieval the core behavior is at least not hidden.

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 short and front-loaded, with no wasted elaboration. The three clauses each carry information, although 'Catalog entry' and 'Runs in your Kuudo deployment, not here' overlap somewhat and could be consolidated.

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?

Given no annotations, an empty schema, and no output schema, the description provides the minimum viable information: operation, input identifier, and execution environment. It leaves ambiguity about whether the tool is actually callable from this context, and gives no return format or error expectations, so an agent would still be uncertain when invoking it.

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?

With zero parameters in the schema, the baseline is 4, and the description adds the crucial parameter name purchaseOrderNumber. It does not specify the type or format of that identifier, but it is the only documentation the schema does not provide and is sufficient to construct a call with additionalProperties allowed.

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 clearly identifies the operation as returning a packing slip and names the key lookup key, purchaseOrderNumber. It is less crisp than ideal because 'Catalog entry' and 'Runs in your Kuudo deployment, not here' introduce environment caveats without clarifying whether this is the actual execution path, but the core purpose is specific.

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?

The description implies use when you have a purchaseOrderNumber and need a single packing slip, and it gives an environment caveat (runs in Kuudo, not here). It does not name alternatives such as getPackingSlips for multiple slips or compare with the 20211228 version, so routing to the right sibling is left to inference.

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