purchase_order_getReturn one purchase order in full by id or exact supplier name: buyer and supplier blocks, every line with unit price and VAT, totals, the delivery date, status and every receipt with its date and note.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001, or an exact supplier name |
Changes observed during successful MCP inspections.
Input schema / additionalPropertiesRemoved value: -falseDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description usefully discloses the return payload (buyer/supplier blocks, lines with unit price and VAT, totals, delivery date, status, receipts with date and note), which is real behavioral value since there is no output schema. However, it frames the operation as a pure retrieval while the annotations declare readOnlyHint=false and idempotentHint=false — an agent cannot tell whether calling this mutates or locks anything. The description also does not say what happens when a supplier name matches more than one order, despite promising to return exactly one.
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?
One front-loaded sentence that wastes no words and puts the operation and lookup key before the payload enumeration. It is dense but scanable; the only cost is that the long clause chain into the returned fields reads like a list rather than prioritized structure.
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 no output schema, the description carries the return-value burden and does so thoroughly for a simple single-parameter lookup. Missing pieces are the sibling routing (list vs text vs pdf) and the multi-match/idempotency behavior, but nothing essential to invoking it is absent.
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 100% and the single parameter is already documented as 'PO-2026-0001 or an exact supplier name'; the description simply repeats that. No extra meaning (format rules, case sensitivity, multiple-match behavior) is added beyond the schema, so the baseline of 3 applies.
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 ('Return one purchase order in full') and immediately scopes it ('by id or exact supplier name'), which cleanly separates it from the list tool in the sibling set. It also enumerates the returned content, so an agent knows exactly what it gets without opening a schema.
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?
Usage is only implied: 'one purchase order in full' hints that this is the detailed single-record read versus purchase_order_list, and probably versus purchase_order_text/purchase_order_pdf. But no alternative is named and no condition for choosing between them is given, so the agent must infer the routing itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.