VendorOrdersV1_getPurchaseOrder

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

There are no annotations, so the description carries the burden of explaining behavior. It indicates a read-style operation by saying 'Returns a purchase order,' but it does not disclose side effects, permissions, rate limits, output format, or error behavior. 'Catalog entry' and 'not here' do not meaningfully address these gaps.

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 mostly front-loaded, with the key behavior stated clearly. The opening 'Catalog entry' is filler, and 'not here' is vague, so not every sentence earns its place, but overall it is appropriately concise.

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 simple lookup tool, the description gives the essential selection key and a deployment note. However, with no output schema and no information about response shape, errors, or how to pass purchaseOrderNumber, the agent is left with meaningful gaps.

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?

The schema declares no properties, so the description adds crucial meaning by naming purchaseOrderNumber as the value to specify. This compensates for the empty schema, though it is inconsistent with the formal zero-parameter signal and does not provide the parameter type or format.

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 the core behavior: it returns a purchase order based on a purchaseOrderNumber. The singular wording distinguishes it from the plural sibling getPurchaseOrders, but it does not explicitly name that alternative. The phrase 'Catalog entry' is vague and adds little.

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 the tool should be used when a specific purchaseOrderNumber is available and mentions a deployment constraint: it runs in the Kuudo deployment, not here. However, it does not explicitly say when not to use it or compare it with related tools like VendorOrdersV1_getPurchaseOrders.

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